You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
mv-api-spec/openapi
Nathanaël Jourdane 026d5e9c4c
Rename responses, schemas, and securityScheme files to fit naming convention
4 years ago
..
components Rename responses, schemas, and securityScheme files to fit naming convention 4 years ago
paths Rename responses, schemas, and securityScheme files to fit naming convention 4 years ago
README.md Initial commit from create-openapi-repo 4 years ago
mv-openapi-root.yaml rename openapi root file 4 years ago

README.md

The openapi folder

This folder contains your entrypoint openapi.yaml.

That file contains references to the entire API definition.

Here are some sections to pay attention to:

  • Top-level description: this accepts markdown, and Redoc and Redocly API Reference will render it at the top of the docs. Consider maintaining your markdown in a separate file and embedding it. Note to Redoc community edition users, the special tags are only available to the Redocly API Reference users, but you can still embed markdown.
  • Security schemes: you will define the scheme(s) your API uses for security (eg OAuth2, API Key, etc...). The security schemes are used by the Redocly API Reference "Try It" API console feature.
  • Paths: this defines each endpoint. A path can have one operation per http method.
  • Tags: it's a good idea to organize each operation. Each tag can have a description. The description is used as a section description within the reference docs.
  • Servers: a list of your servers, each with a URL.