FAQ

Why is the request/response body empty even with a schema object present?

Ensure that your schema object includes a defined type. If a type is not specified, the table will display the text <type>. Merely having properties present does not suffice to indicate that the schema is categorized as an object.

For example:

content:

  application/json:

    schema:

      properties:

        id:

          type: number

        name:

         type: string

How do I reorder Operations?

Operations, such as GET /version and POST /reference, are organized in the precise sequence they appear within the OpenAPI definition. Although we employ tags to categorize these operations for easier navigation, it's crucial to understand that we maintain their original order without any modifications. For instance:

# If the operations and tags are specified as such in the API definition:

​

paths:

  '/cat':

    post:

      tags:

        - Cats

      ...

    get: 

      tags:

        - Cats

      ...

  '/dog':

    get: 

      tags:

        - Dogs

      ...

    post: 

      tags:

        - Dogs

      ...

tags:

  - name: 'Dogs'

  - name: 'Cats'

# The operations and tags would be ordered as such in the API reference:

​

# Dogs

#   GET  /dog

#   POST /dog

# Cats

#   POST /cat

#   GET  /cat

You are encouraged to rearrange the operations within your OpenAPI definition to create an optimal and seamless experience for your readers. This flexibility allows you to present the information in a way that enhances understanding and navigation through your API documentation.