Merge pull request #51 from PaystackOSS/feat-dev-exp

Feat dev exp

Author: damilola-paystack

README.md

@@ -9,16 +9,32 @@ You can download the specification and make use of it on:
 - [SwaggerHub](https://swagger.io/tools/swaggerhub/)
 - [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)
 
+## Set up locally
+- Clone repo
+  ```sh
+  git clone [email protected]:PaystackOSS/openapi.git
+  ```
+- Navigate to the cloned project and install dependencies
+  ```sh
+  cd openapi
+  pnpm install
+  ```
+- Start the server to view the spec in your browser
+  ```sh
+  pnpm dev
+  ```
+  > [!NOTE]
+  > At the moment, the `paystack.yaml` file is the only spec that is automatically opened in your browser. If the spec doesn't open automatically in your browser, you can manually open http://localhost:3031 in your browser.
+
 ## Components
-There are three main folders of interest in this repo:
-- `main`: This contains a comprehensive specification of the Paystack API:
-  - `resources`: This contains individual endpoints in each API category
-  - `responses`: This contains the models for responses
-  - `schemas`: This contains models for each endpoint 
-  - `paystack.yml`: This is the entry point for all components
+There are two top-level folders of interest in this repo:
+- `src`: This contains the assets, scripts and basic .html for working and viewing the OpenAPI Specification (OAS) file.
+  - `assets`: This contains the Paystack OAS files:
+    - `base`: Default single OAS file that was used to rebuild codebase (to be removed)
+    - `openapi`: This contains the individual, manageable parts of the OAS
+    - `sdk`: This is a single file specification being used for client library generation. It contains just enough parameters for our client libraries (might be removed later).
+    - `use_cases`: This is a collection of specifications containing APIs for common use cases of the Paystack API. For example, the `wallet.yaml` contains the APIs needed to build a wallet feature into your application. The specifications in this directory are used to create the collections in our [Postman Workspace](https://www.postman.com/paystack-developers?tab=collections).
 - `dist`: Not all OpenAPI readers can read from different file sources, so we built a single file from all the components in the `main` directory.
-- `sdk`: This is a single file specification being used for client library generation. It contains just enough parameters for our client libraries.
-- `use_cases`: This is a collection of specifications containing APIs for common use cases of the Paystack API. For example, the `wallet.yaml` contains the APIs needed to build a wallet feature into your application. The specifications in this directory are used to create the collections in our [Postman Workspace](https://www.postman.com/paystack-developers?tab=collections).
 
 ## Contributing
 Here are some of the ways to contribute to this repository:
@@ -27,7 +43,7 @@ Here are some of the ways to contribute to this repository:
 - Suggest an improvement
 
 ## Issues
-Kindly [open an issue](https://github.com/PaystackOSS/openapi/issues) if you discover any bug or have problems using this library.
+You can [open an issue](https://github.com/PaystackOSS/openapi/issues) if you discover any bug or have problems using this repo.
 
 ## License
 This repository is made available under the MIT license. Kindly read the [LICENSE](https://github.com/PaystackOSS/openapi/blob/main/LICENSE) file for more information.