OpenAPI Basics

Docs structure

Documentation follows OpenAPI 3.1 Specification extended by Swagger and Redoc fields. The main structure is as in the original specification.

Info

info attribute contains all basin information displayed on the main page:

• title - Documentation title (do not put version here
• version - Semantic Versioning valid version
• description - markdown description, usually included as a $ref to .md file

  description:
    $ref: ./info-description.md

• termsOfService - link to T&C page
• contact - contact details

  contact:
    email: ceo@zhiva.ai
    url: 'https://zhiva.ai/contact'

• license - license information

Tags

Before defining navigation we have to define a list of tags that can be later added into navigation groups. Each tag has to be unique (name attribute). Sample tags looks like:

tags:
  - name: pet
    description: Everything about your Pets
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user

Navigation

Navigation structure is defined in x-tagGroups attribute inside .yaml file. This attribute is structured as follows:

x-tagGroups:
  - name: General
    section: database
    tags:
      - pet
      - store
  - name: User Management
    section: authentication
    tags:
      - user
  - name: Models
    section: storage
    tags:
      - pet_model
      - store_model

Each x-tagGroup is assigned to section which corresponds to one of the categories defined in ./config.js. This group (and all of its tags) will be displayed under the section.

Endpoints

Endpoints are defined in paths attribute. Path to each endpoint consists of paths -> endpoint -> http_method, example:

paths:
  /pet:
    post:

Specifies POST request to /pet endpoint. This endpoint is assigned to the tags attribute for its own definition. It will be displayed under each specified tag in the Navigation component.