A template for OpenAPI Specification projects.

This project breaks the Swagger Petstore example from the official documentation into smaller files. It also adds some handy commands to build, lint, and preview the OpenAPI specification from the command-line.

Either if you want to create a new OpenAPI document from scratch or you already have it defined, you can use this template as a guide to structuring your project.

• Multi-file Support: Define the OpenAPI document in different files.
• Merge OpenAPI files: Merge all the separate files into one with swagger-cli
• Specification Validation: Validate and lint the OAS document with spectral
• Reference Documentation: Generate API Reference documentation with ReDoc
• GitHub Pages Support: Publish the API Reference on GitHub Pages

• Node.js 14 LTS

1. Clone the repository.

git clone https://github.com/dgarcia360/openapi-boilerplate.git

2. Install the project dependencies.

npm install

3. Edit openapi.yaml to fit your API definition. If you are not familiar with the OpenAPI Specification, it's worth taking a look first to the documentation.

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

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://127.0.0.1:8080

The project uses GitHub Actions for Continous Integration.

On every new pull request, the OpenAPI document is linted with spectral. If there are changes that introduce errors, the bot will highlight them replying to the pull request.

When the default branch (master) receives an update, a workflow automatically publishes the API reference documentation site to GitHub Pages. The site is generated with ReDoc.

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.