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 as a starting point, whether you are creating a new OpenAPI document from scratch or splitting an existing one into multiple files.
- 📝 Write OpenAPI definitions in different files.
- 🔀 Combine all files with redocly-cli.
- ✅ Validate and lint the OpenAPI document with Spectral.
- ✨ Publish reference docs with Scalar & GitHub Pages.
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.
I've found that splitting a large spec into smaller files makes it easier to maintain and encourages other devs to contribute, as the structure feels more approachable.
- Node.js 18+
-
Clone the repository.
git clone https://github.com/dgarcia360/openapi-boilerplate.git -
Install the project dependencies.
npm install -
Edit the files under
src/to 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 bundled document is stored in _build/openapi.yaml.
The command checks if the document follows the OpenAPI 3.1 Specification.
npm run test
The command builds a docs site so that you can view the rendering on your local browser.
npm run preview
The server starts on http://localhost:3000.
The site is generated with Scalar. Here's a preview: Swagger Petstore Reference Documentation.
The project uses GitHub Actions for Continuous Integration (CI).
On every new pull request, the OpenAPI document is linted with Spectral. If there are changes that introduce errors, the workflow will fail and highlight them.
On every push to master and on pull requests, the build is tested against Node 18, 20, and 22.
When the default branch (e.g. master) receives an update, a workflow automatically publishes the API reference documentation site to GitHub Pages. This workflow can also be triggered manually from the Actions tab.
See .github/workflows to customize the available workflows. If you don't plan to use GitHub to host your spec or prefer to keep docs private, delete the .github folder.
Contributions are welcome and appreciated! If you want to enhance the boilerplate, please read CONTRIBUTING.md file first.
Copyright (c) 2019-present David Garcia (@dgarcia360). Licensed under the MIT License.
The PetStore example used is derived from OAI/OpenAPI-Specification, Copyright The Linux Foundation, Licensed under the Apache License, Version 2.0.