How to write a YAML file for Swagger UI

Swagger UI is a powerful tool for documenting and testing APIs. It allows us to visualize and interact with the endpoints of an API, making it an essential component for ensuring the usability and understanding of our API. We need a well-structured and informative documentation.yaml file to make the most out of Swagger UI. In this Answer, we’ll go through the process of creating a documentation.yaml file for Swagger UI.

Note: Click here to learn how to build a RESTful API.

Understanding the basics

Before we start crafting our documentation.yaml file, it’s crucial to clearly understand the structure and purpose of Swagger documentation. Swagger uses YAML or JSON files to define API specifications. These files provide information about the API’s endpoints, request and response formats, and other critical details.

The documentation.yaml file serves as the blueprint for our API’s documentation, helping users to understand and interact with our API effortlessly.

Writing a `documentation.yaml` file for Swagger UI

Follow the steps given below to write the documentation.yaml file for the Swagger UI:

Step 1: Specify swagger specification, info, and server section

The swagger specification is a standard for documenting RESTful APIs. It allows us to define our API’s endpoints, request parameters, and response formats. Swagger UI is built around this specification. We’ll start the documentation.yaml file by adding the following information:

OpenAPI version: The openapi field specifies the swagger specification version, such as OpenAPI 3.0.0. We’ll use a compatible version of the specification.
Information section (Info): The info section provides general information about our API. Replace the title, description, and version with specific details about our API. This information will be displayed in our Swagger UI.
Servers section: The servers section defines the base URL where our API is hosted. We can provide multiple entries under the servers section if our API is hosted on multiple servers. We’ll replace https://App with our actual API URL.

Step 2: Define endpoints

In the paths section, we define the different routes of our API. For each of the endpoints in our API, we’ll add the following information:

HTTP method: Specify the HTTP method (e.g., GET, POST, PUT) and provide relevant details.
1. Description: We describe what each route does in the description field. This helps users understand the purpose of the route.
2. Parameters: For routes that accept parameters, we define them under the parameters section. Include details like parameter name, location (e.g., query, path), and data type.
3. Request Body (if applicable): We specify the structure of the request body if the route expects one. Make sure to reference the corresponding schema defined in the components section (We will discuss components section in Step 3).
4. Responses: We define the possible responses for each route, including the HTTP status code, a description, and the expected response structure.

paths:
  /endpoint:
    httpMethod:
      summary: Retrieve data
      description: Retrieve data from the API.
      parameters:
      - name: limit
        in: query
        description: The maximum number of items to return
        required: false
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                age:
                  type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

Step 4: Validation (optional)

After creating or updating our documentation.yaml file, we’ll validate it using an OpenAPI validator or the Swagger Editor to ensure it adheres to the OpenAPI Specification and to check for any errors.

Step 5: Security (optional)

We can further customize our Swagger documentation by adding information such as authentication mechanisms, security definitions, or additional metadata specific to our API. In the code below, we define different security schemes to be used by the API in the global components/securitySchemes section. We then apply them to the whole API by adding the security section on the root level. This will apply the specified security schemes globally to all API operations.

openapi: 3.0.0
info:
  title: Educative API
  description: This is a sample Educative API.
  version: 1.0.0
servers:
  - url: "https://EducativeAPI"
paths:
  /users:
    get:
      summary: Get a list of users
      description: Get a list of users from the API.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                users:
                  - id: 1
                    name: John Doe
                  - id: 2
                    name: Jane Doe
    post:
      summary: Create a new user
      description: Add a new user information using the API.
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: New User
      responses:
        '201':
          description: User created successfully
  /users/{id}:
    get:
      summary: Get user by ID
      description: Get a single user from the API.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                id: 1
                name: John Doe
        '404':
          description: User not found