create-swagger-ui-with-sidebar

Swagger UI with Sidebar

Dashboard with sidebar for multiple Swagger definitions

---

Usage

$ npx create-swagger-ui-with-sidebar@latest docs #folder name can be anything

Navigate to folder, and install dependencies and then start development serve

$ cd docs && npm run dep && npm run dev

That's you can edit config and add definitions to public folder or reference remote files

---

Configuration (project-directory/config.js)

Config Property
config.definitions	List of definition names and their URLs (icons coming soon)
config.sidebarConfig	Update title, and extend theme
config.swaggerUIProps	Add additional props for Swagger UI react

Folder structure

|- 📁 root # Project directory
    |- 📁 public/ # Files to be served at the root of the project
        |- 📁 assets/ # Logo for sidebar and favicon for browser
            |- 🖼 logo.svg
            |- 🖼 favicon.ico
        |- 📁 definitions/ # Local definitions
            |- 📝 {definition}.{yaml|json}
            |- 📝 ...
            |- 📝 ...
    |- 📁 template/ # The react project, normally you don't need to edit the files here
        |- 📁 src # Source code for react app
    |- 📝 config.js # Configuration file for entire project
    |- 📝 package.json # Contains script to interact with template project

Motivation

Wanting to document multiple AWS API gateway services where each service is also deployed on 3 environment (servers) in one location and make it easy to manage multiple swagger definition files.

A sidebar seemed to be the best solution, so that's how this project was created as a weekend project.

How it works

The base template is a vite react-ts project that is very customizable. While you can edit all of the the source file, the intention of this is that you don't have to.

All you should need to do it update the config.js and add definitions to the public folder.

Swagger definitions are handled by the Swagger UI React module

And finally, the sidebar was created with components from Chakra UI

---

Road Map

- [x] Create Swagger UI project with sidebar from on command
- [x] Add brand/color options (based on Chakra UI colors)
- [] Expose customization for **config** file through CLI
- [] Expose customization for **Swagger UI** props through CLI
- [] Add continuation option for perviously created projects
- [] Add icons support for sidebar (maybe FontAwesome)
- [x] Allow rebuild of existing project for config changes outside of development
- [] Delete template folder on build (optional)