search

beckn / beckn-onix

beckn onix
MIT License
52 stars 28 forks source link

Integrate Swagger UI into the beckn-onix repository. #242

Closed rajaneeshk90 closed 1 month ago

rajaneeshk90 commented 1 month ago

Summary:

This Pull Request integrates Swagger UI into the repository to host and provide an interactive visualization of the Beckn-ONIX specification. With this integration, users will be able to explore and interact with the OpenAPI specification of Beckn-ONIX directly from the GitHub repository through a web interface.

This PR utilises Swagger UI for this integration, which simplifies the exploration of API documentation and provides an intuitive user interface for testing endpoints.

Integration Details:

The following steps were taken to integrate Swagger UI into the repository:

  1. Clone Swagger UI: The Swagger UI repository was cloned locally to add it as a part of the project. git clone https://github.com/swagger-api/swagger-ui.git

  2. Copy the Swagger UI files: Content of the /dist folder from the Swagger UI repository were copied into /swagger directory inside this beckn-onix repository to serve the documentation.

  3. Link the Beckn-ONIX OpenAPI Specification: The OpenAPI specification file (specification/specification.yaml ) was linked to the Swagger UI configuration in swagger-initializer.js to render the API documentation.

  4. Hosting the Swagger UI: Since Swagger UI serves files only from /doc or / folder, we added an index.html file at the root of the repository to redirect the requests to the swagger/index.html.

  5. Merge the change: Merge the above changes in the repository (We can merge it in any branch)

  6. Change the settings in the repository: Go to your GitHub repository.

    • Click on Settings.
    • Scroll down to the GitHub Pages section.
    • Under Source, select the branch where you uploaded the dist folder (usually main or master), and choose /root as the directory.

  7. Test and Verify: GitHub Pages will now serve your static files. Your Swagger UI will be available at https://<your-username>.github.io/<your-repository-name>/

Benefits:

  1. Provides an interactive interface for exploring and testing Beckn-ONIX APIs.
  2. Simplifies onboarding for developers by enabling them to view API documentation within the repository.
  3. Encourages consistent use of OpenAPI standards by hosting the spec in a format that is accessible and usable.