A starter template for OpenAPI Specification (OAS) projects.
This project splits the Swagger Petstore example from the official documentation into smaller files. It also adds handy commands to build, lint, and preview the OpenAPI document from the terminal.
You can use this template to guide the organization of your project. Either if you want to create a new OpenAPI document from scratch or if you already have it defined.
- 📝 Write OpenAPI definitions in different files.
- 🔀 Combine all files with APIDevTools/swagger-cli.
- ✅ Validate and lint the OpenAPI document with stoplight/spectral.
✨ Publish reference docs with redocly/redoc & GitHub Pages.(simplified on this fork)
When I used to document APIs following the OpenAPI spec, I always ended up with documents of thousands of lines, which were a nightmare to maintain.
For this reason, I explored how to split OpenAPI documents. Jump over to my blog to learn more about the process. Based on my research, I created this opinionated template to define, test, and publish modular OpenAPI projects.
Properly organizing your project comes with great advantages. By splitting a large OpenAPI spec into multiple files, it will not only be much easier to handle. Documenting it will be much more enjoyable, too. I also regularly get the feedback that other developers are more willing to contribute and propose changes to the document with this structure.
- Node.js 16 (current)
-
Clone the repository.
git clone https://github.com/dgarcia360/openapi-boilerplate.git -
Install the project dependencies.
npm install -
Edit
openapi.yamlto fit your API definition. If you’re not familiar with the OpenAPI Specification, read Getting started with OAS first.
The project will build, lint, and preview the OpenAPI document from the terminal, with the following commands:
The command bundles the spec as one .yaml file.
npm run build
The minified document is stored in _build/openapi.yaml.
The command checks if the document follows the OpenAPI 3.0 Specification.
npm run test