dgarcia360 / openapi-boilerplate Goto Github PK

View Code? Open in Web Editor NEW

361.0 6.0 85.0 2.83 MB

📘 Multi-file boilerplate for Open API Specification

Home Page: https://dgarcia360.github.io/openapi-boilerplate/

License: Other

Shell 100.00%

openapi swagger api-documentation documentation-boilerplate openapi3

openapi-boilerplate's Introduction

OpenAPI boilerplate

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.

Features

📝 Write OpenAPI definitions in different files.
🔀 Combine all files with redocly-cli.
✅ Validate and lint the OpenAPI document with stoplightio/spectral.
✨ Publish reference docs with Redoc & GitHub Pages.

Why?

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.

Getting started

Requirements

Node.js 16 (current)

Installation

Clone the repository.

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

Install the project dependencies.
```
npm install
```
Edit openapi.yaml to fit your API definition. If you’re not familiar with the OpenAPI Specification, read Getting started with OAS first.

Useful commands

The project will build, lint, and preview the OpenAPI document from the terminal, with the following commands:

Build

The command bundles the spec as one .yaml file.

npm run build

The minified document is stored in _build/openapi.yaml.

Test

The command checks if the document follows the OpenAPI 3.0 Specification.

npm run test

Preview

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 site is generated with ReDoc. Here's a preview of a site generated with this command: Swagger Petstore Reference Documentation.

Ready-to-use workflows

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 bot will highlight them replying to the pull request.

When the default branch (e.g. master) receives an update, a workflow automatically publishes the API reference documentation site to GitHub Pages.

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.

Contributing

Contributions are welcome and appreciated! If you want to enhance the boilerplate, please read CONTRIBUTING.md file first.

License

The PetStore example used is derived from OAI/OpenAPI-Specification, Copyright The Linux Foundation, Licensed under the Apache License, Version 2.0.

openapi-boilerplate's People

Contributors

Stargazers

Watchers

Forkers

wako057 snorrika tagyoureit ashwinrs kbrikh forestlzj araujoma ignaciobll mayhs19 tegu-dev tthoppek hall-forks domix s-khuntia mikeralphson raphaelblehoue johanra ajaxsys pratik12 nabeel1121014 hongquanto jansteffes mikelax robertweidekyos igrokqq osteinhauer muskanmahajan37 kscheirer dev-dennis-guye royalchan-okta sanz gabriel-son glafeara bencekocsmar nina0408 shshohagh mcnguyen mju-solutions aker all0fme khunii mauriziocasciano bhatikuldeep shortcarver rayblair06 rigo101 chiragurw yichingwu bkzhn-knockcrm gjohnsondpp airlambda anatomicjc alexcrawford raghumurthy-jayandran avall giulifed-coder rahuldhawan291 abhinaba-ghosh sangjielmz zcsantos jonico mohdqasim98 daniilolacerda onmomo antonioramospeya yang-wansu dubchuck maxsuren andy-hay jstol atoo goydykovakristi grailoun broklyngagah mani1128 guillemparrado smcpeck icej-jr solehudin5699 interserver teejay8211 mazhario1 jayjay-101

openapi-boilerplate's Issues

Unclear which license applies

There are 3 different license informations spread over the repository.

The package.json defines Apache 2.0 as the package license.
The LICENSE.md specifies MIT, as does the GitHub Repo, as does the header of the README.md
The bottom of the README.md includes a License chapter, that only lists a Copyright of the creator.

Could you please clarify and maybe homogenize the license of this repository/project?

Reusing the same paths defenitions for different versions of the docs

Hi!

Thanks for the boilerplate and for usefull article!
But how can I reuse the same paths defenitions for different versions of the docs with the only different schema or properties definitions?

Is there any way to use variables in $ref's of the paths defenitions? Or is it possible to use relative (internal) links within $ref descriptions of the paths defenitions that not binded with concrete shemas files?

I mean if I want to create different versions of the OpenApi documentation (for developers and public for ex.) and there are only differences in schemas elements descriptions for dev and public versions. Is it possible to change the $ref for example from "../schemas/Pet.yaml" to "#/components/schemas/Pet" in path defenition and then make two different files (/schemas/Pet-dev.yaml and /schemas/Pet-public.yaml) and two openapi-public.yaml and openapi-dev.yaml main files with different components/schemas $refs (' $ref: "./schemas/pet-open.yaml" and $ref: "./schemas/pet-dev.yaml" '). in theory it may give the possibility reuse the same paths defnitions for both dev and open docs.

Unfortunately for now $ref's with internal links, like "#/components/schemas/Pet" cause an error at the building of the final doc file. And using external links like "../schemas/Pet.yaml" in paths $refs makes hard binding paths defenition with schema defenition so it doesn't allow me to reuse path defenition for different version of the docs.
Could you give me the advice?

Removing unnecessary clutter

Thank you for the template!
I deleted all _index.yaml files and removed all references to them, and the spec passes linters & builds without any problems. Is there a reason for those files & their references to exist that I'm not aware of?

OpenAPI Generator Question

Hi @dgarcia360 and thank you for the repo.

I have a question regarding the openapi-generator. When I run your project through it, it does not validate.

See:

~/openapi-boilerplate/src master
❯ openapi-generator validate -i openapi.yaml
Validating spec (openapi.yaml)
Errors:
	- attribute components.responses.$ref is not of type `object`
	- attribute components.schemas.$ref is not of type `object`
	- attribute components.schemas.Schema name $ref doesn't adhere to regular expression
	  ^[a-zA-Z0-9\.\-_]+$
	- attribute components.responses.Response key $ref doesn't adhere to regular expression
	  ^[a-zA-Z0-9\.\-_]+$
	- attribute components.parameters.Parameter name $ref doesn't adhere to regular expression
	  ^[a-zA-Z0-9\.\-_]+$

[error] Spec has 5 errors.

Thank you for your help.

Update node version in gh-pages.yml workflow file

Thank you for putting this templated repo together! I found it extremely useful when utilizing it in my own project.

Bug Summary

A recent build following the workflow file gh-pages.yml resulted in the below error:

internal/modules/cjs/loader.js:818
  throw err;
  ^

Error: Cannot find module 'react-is'

Click for full error message

Run npm ci
added 414 packages in 4.487s

> [email protected] build /home/runner/work/daeclipse/daeclipse
> swagger-cli bundle spec/openapi.yaml --outfile _build/api/openapi.yaml --type yaml

Created _build/api/openapi.yaml from spec/openapi.yaml

> [email protected] html /home/runner/work/daeclipse/daeclipse
> npm run build && redoc-cli bundle _build/api/openapi.yaml  --output _build/api/index.html --options.onlyRequiredInSamples


> [email protected] build /home/runner/work/daeclipse/daeclipse
> swagger-cli bundle spec/openapi.yaml --outfile _build/api/openapi.yaml --type yaml

Created _build/api/openapi.yaml from spec/openapi.yaml
internal/modules/cjs/loader.js:818
  throw err;
  ^

Error: Cannot find module 'react-is'
Require stack:
- /home/runner/work/daeclipse/daeclipse/node_modules/redoc-cli/node_modules/styled-components/dist/styled-components.cjs.js
- /home/runner/work/daeclipse/daeclipse/node_modules/redoc-cli/index.js
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:815:15)
    at Function.Module._load (internal/modules/cjs/loader.js:667:27)
    at Module.require (internal/modules/cjs/loader.js:887:19)
    at require (internal/modules/cjs/helpers.js:74:18)
    at Object.<anonymous> (/home/runner/work/daeclipse/daeclipse/node_modules/redoc-cli/node_modules/styled-components/dist/styled-components.cjs.js:1:145)
    at Module._compile (internal/modules/cjs/loader.js:999:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1027:10)
    at Module.load (internal/modules/cjs/loader.js:863:32)
    at Function.Module._load (internal/modules/cjs/loader.js:708:14)
    at Module.require (internal/modules/cjs/loader.js:887:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/home/runner/work/daeclipse/daeclipse/node_modules/redoc-cli/node_modules/styled-components/dist/styled-components.cjs.js',
    '/home/runner/work/daeclipse/daeclipse/node_modules/redoc-cli/index.js'
  ]
}
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] html: `npm run build && redoc-cli bundle _build/api/openapi.yaml  --output _build/api/index.html --options.onlyRequiredInSamples`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] html script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/runner/.npm/_logs/2021-08-07T15_20_03_874Z-debug.log
Error: Process completed with exit code 1.

Link to build: https://github.com/Pepper-Wood/daeclipse/runs/3269822656

Proposed Solution

Thanks to this comment - nodejs/help#1846 (comment) - a working fix was to update the node version that's listed in the gh-pages.yml workflow file.

Link to my code change: kdipippo/daeclipse@5dac86f

Following the diff here should be able to future-proof if any others run into the same issue with attempting to deploy.

A `$ref` is not allowed directly under `path`

Per https://swagger.io/docs/specification/using-ref/, this is invalid:

paths:
  $ref: "./paths/_index.yaml"

You can do this however:

paths:
  /pets:
    $ref: "./paths/listPets.yaml"

listPets.yaml (added the get node)

get:
  summary: List all pets
  operationId: listPets
  tags:
    - pets
  parameters: