Amrish
Amrish

Reputation: 697

Generating Schema in API documentation with redocly

I am using redocly for generating API documentation. Currently redocly generates API documentation for endpoints (paths), but does not generate schema documentation. This blog on their website explains how to generate the schema section by settingschemaDefinitionsTagName value to Schema in the configuration file, but it does not seem to be working here. While I can individually tag each component/schemas definition with <SchemaDefinition schemaRef="#/components/schemas/{SchemaName}" /> it does not seem to be a scalable solution.

Does anyone know of a solution for this?

Here is my .redocly.yaml configuration file

organization: example-org
extends:
  - recommended

apis:
  [email protected]:
    root: ./api-def.yaml

theme:
  openapi:
    schemaDefinitionsTagName: Schemas

This is my api-def.yaml file


openapi: "3.0.3"

info:
  title: Sample Application
  version: "0.1"

servers:
  - url: http://localhost:3000/
    description: localhost
  - url: https://myapp.dev.example.com/
    description: dev server
  - url: https://myapp.qa.example.com/
    description: qa server
  - url: https://myapp.example.com/
    description: prod server

paths:
  /cars:
    post:
      tags:
        - Cars
      operationId: "createCar"
      summary: Create Car
      description: Create a new Car.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Car"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Car"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /cars/{id}:
    put:
      tags:
        - Cars
      operationId: "updateCar"
      summary: Update Car
      description: Update an existing car
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the car to be updated.
          schema:
            type: string
            format: objectId
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Car"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Car"
        '400':
          description: Bad Request. The request body has errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '404':
          description: Not Found. Car with the `:id` parameter not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      tags:
        - Cars
      operationId: "getCar"
      summary: Get Car.
      description: Get car represented by id.
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the car to be looked up.
          schema:
            type: string
            format: objectId
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Car"
        '404':
          description: Not Found. Question with the `:id` parameter not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Car:
      type: object
      properties:
        id:
          type: string
          format: objectId
        manufacturerId:
          type: string
          format: objectId
        description:
          type: string
          description: detail description of the car
        configuration:
          $ref: "#/components/schemas/Configuration"
        category:
          type: string
          description: Category of the car
          enum:
            - sedan
            - suv
            - hatchback
            - atv
        createdAt:
          type: string
          format: date
        updatedAt:
          type: string
          format: date
      required:
        - content
        -

    Configuration:
      oneOf:
        - $ref: "#/components/schemas/V6Configuration"
        - $ref: "#/components/schemas/V8Configuration"

    V6Configuration:
      type: object
      properties:
        id:
          type: string
        description:
          type: string

    V8Configuration:
      type: object
      properties:
        id:
          type: string
        description:
          type: string
          
    Error:
      type: object
      properties:
        name:
          type: string
        code:
          type: number
          description: this would correspond to the HTTP status code of the response.
        description:
          type: string
        data:
          type: object
          description: this object would contain any additional data related to the error.

and this is the command I am using to generate the API documentation

 redocly build-docs --output api-def.html api-def.yaml

And this is what generated documentation looks like. API Documentation Preview

Upvotes: 2

Views: 992

Answers (0)

Related Questions