OpenAPI tutorial step 4: The paths object

The paths object contains the meat of your API information. The paths object has a number of sub-objects: a path items object, an operations object, and more.

My preferred term is “endpoint” rather than “path,” but to be consistent with the terminology of the openAPI spec, I refer to them as “paths” here.

Start by listing the paths

Start by listing the paths (endpoints) and their allowed operations (methods). For the Mashape Weather API, there are just 3 paths, each with the get operation:

paths:
  /aqi:
    get:

  /weather:
    get:

  /weatherdata:
    get:

Operation Objects

Each path item object contains an operation object. Operations are the GET, POST, PUT, and DELETE methods we explored in endpoints definitions and methods. The operation object contains a number of potential properties and objects:

  • tags: A tag to organize the path under when displayed in the Swagger UI. Swagger UI will organize or group endpoints under tag headings.
  • summary: A brief overview of the path. Swagger UI displays the summary next to the path name. Limit the summary to 5-10 words only. The display appears even when this section is collapsed.
  • description: A full description of the path. Include as much detail as you want. There’s a lot of space in the Swagger UI for these details. CommonMark Markdown is allowed.
  • externalDocs (object): Links to documentation for more information about the path.
  • operationId: A unique identifier for the path.
  • parameters (object): Parameters accepted by the path. Does not include request body parameters, which are instead detailed in the requestBody object. The parameters object can also include a reference object that simply contains a pointer to the description in the components object (this is explained in step 5).
  • requestBody (object): The request body parameter details for this path. The requestBody object can also include a reference object that simply contains a pointer to the description in the components object (explained in step 5).
  • responses (object): Responses provided from requests with this path. The responses object can also include a reference object that simply contains a pointer to the description in the components object. Responses use standard status codes.
  • callbacks (object): Callback details to be initiated by the server if desired. Callbacks are operations performed after a function finishes executing. The callbacks object can also include a reference object that simply contains a pointer to the description in the components object.
  • deprecated: Whether the path is deprecated. Omit unless you want to indicate a deprecated field. Boolean.
  • security (object): Security authorization method used with the operation. Only include this object at the path level if you want to overwrite the security object at the root level. The name is defined by the securitySchemes object in the components object. More details about this are provided in the security object.
  • servers (object): A servers object that might differ for this path than the global servers object.

Each of the above hyperlinked properties that say “(object)” contain additional levels. Their values aren’t just simple data types like strings but are rather objects that contain their own properties.

Let’s add a skeleton of the operation object details to our existing code:

paths:
  /aqi:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:
      deprecated:
      security:
      servers:
      requestBody:
      callbacks:

  /weather:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:
      deprecated:
      security:
      servers:
      requestBody:
      callbacks:

  /weatherdata:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:
      deprecated:
      security:  
      servers:
      requestBody:
      callbacks:     

Now we can remove a few unnecessary fields:

  • There’s no need to include requestBody object here because none of the Mashape Weather API paths contain request body parameters.
  • There’s no need to include the servers object because the paths just use the same global servers URL that we defined globally at the root level.
  • There’s no need to include security because all the paths use the same security object, which we defined globally at the root (see step 6).
  • There’s no need to include deprecated because none of the paths are deprecated.
  • There’s no need to include callbacks because our paths don’t use callbacks.

As a result, we can reduce the number of fields to concern ourselves with:

paths:
  /aqi:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:

  /weather:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:

  /weatherdata:
    get:
      tags:
      summary:
      description:
      operationId:
      externalDocs:
      parameters:
      responses:      

You’ll undoubtedly need to consult the OpenAPI spec to see what details are required for each of the values and objects here. I can’t replicate all the detail you need, nor would I want to. I’m just trying to introduce you to the OpenAPI properties at a surface level.

Most of the properties for the operation object either require simple strings or include relatively simple objects. The most detailed object here is the parameters object.

Parameters object

The parameters object contains an array (list designated with dashes) with these properties:

parameters:

  • name: Parameter name.
  • in: Where the parameter appears. Possible values: header, path, query, or cookie. (Request body parameters are not described here.)
  • description: Description of the parameter.
  • required: Whether the parameter is required.
  • deprecated: Whether the parameter is deprecated.
  • allowEmptyValue: Whether the parameter allows an empty value to be submitted.
  • style: How the parameter’s data is serialized (converted to bytes during data transfer).
  • explode: Advanced parameter related to arrays.
  • allowReserved: Whether reserved characters are allowed.
  • schema (object): The schema or model for the parameter. The schema defines the input or output data structure. Note that the schema can also contain an example object.
  • example: An example of the media type. If your examples object contains examples, those examples appear in Swagger UI rather than the content in the example object.
  • examples (object): An example of the media type, including the schema.

Rather than defining the schema here, it’s common to place a $ref (reference) pointer to a fuller definition in the components object. This approach also allows you to single source the schema, because now you can have many references pointing to the same defined schema in components. You can use the same technique for responses, parameters, and other properties. I explain more about using $ref below in Re-using definitions across objects and in step 5.

Here’s the operation object defined for the Mashape Weather API:

paths:
  /aqi:
    get:
      tags:
      - Air Quality
      summary: getAqi
      description: Gets the air quality index
      operationId: GetAqi
      externalDocs:
        description: More details
        url: "https://market.mashape.com/fyhao/weather-13#aqi"
      parameters:

      - name: lat
        in: query
        description: "Latitude coordinates."
        required: true
        style: form
        explode: false
        schema:
          type: string
        example: "37.3708698"

      - name: lng
        in: query
        description: "Longitude coordinates."
        required: true
        style: form
        explode: false
        schema:
          type: string
        example: "-122.037593"

      responses:
        200:
          description: AQI response
          content:
            text/plain:
              schema:
                type: string
                description: AQI response
                example: 52
  /weather:
    get:
      servers:
      - url: https://simple-weather.p.mashape.com
      tags:
      - Weather Forecast
      summary: getWeather
      description: Gets the weather forecast in abbreviated form
      operationId: GetWeather
      externalDocs:
        description: More details
        url: "https://market.mashape.com/fyhao/weather-13#weather"
      parameters:

      - name: lat
        in: query
        description: "Latitude coordinates."
        required: true
        style: form
        explode: false
        schema:
          type: string
        example: "37.3708698"

      - name: lng
        in: query
        description: "Longitude coordinates."
        required: true
        style: form
        explode: false
        schema:
          type: string
        example: "-122.037593"

      responses:
        200:
          description: weather response
          content:
            text/plain:
              schema:
                type: string
                description: weather response
                example: 26 c, Mostly Clear at Singapore, Singapore

  /weatherdata:
    get:
      tags:
      - Weather Forecast
      summary: getWeatherData
      description: Get weather forecast with lots of details
      operationId: GetWeatherData
      externalDocs:
        description: More details
        url: "https://market.mashape.com/fyhao/weather-13#weatherdata"
      parameters:

      - name: lat
        in: query
        description: "Latitude coordinates."
        required: true
        style: form
        explode: false
        schema:
          type: string
        example: "37.3708698"

      - name: lng
        in: query
        description: "Longitude coordinates."
        required: true
        style: form
        explode: false
        schema:
          type: string
        example: "-122.037593"

      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Successful operation
                $ref: '#/components/schemas/WeatherdataResponse'

Re-using definitions across objects

In this API, the lat and lng parameters are duplicated in each path. Copying and pasting this information multiple times is inefficient and can lead to inconsistency. The OpenAPI spec allows you to single source the parameter information from a common definition.

I’ll dive into more details in the components step, but for now, note that we can use a $ref property to refer to more details in the components object. See how parameters simply contains a reference object:

paths:
  /aqi:
    get:
      tags:
      - Air Quality
      summary: getAqi
      description: Gets the air quality index
      operationId: GetAqi
      externalDocs:
        description: More details
        url: "https://market.mashape.com/fyhao/weather-13#aqi"
      parameters:
        - $ref: '#/components/parameters/latParam'
        - $ref: '#/components/parameters/lngParam'
      responses:
        200:
          description: AQI response
          content:
            text/plain:
              schema:
                type: string
                description: AQI response
                example: 52
  /weather:
    get:
      servers:
      - url: https://simple-weather.p.mashape.com
      tags:
      - Weather Forecast
      summary: getWeather
      description: Gets the weather forecast in abbreviated form
      operationId: GetWeather
      externalDocs:
        description: More details
        url: "https://market.mashape.com/fyhao/weather-13#weather"
      parameters:
        - $ref: '#/components/parameters/latParam'
        - $ref: '#/components/parameters/lngParam'
      responses:
        200:
          description: weather response
          content:
            text/plain:
              schema:
                type: string
                description: weather response
                example: 26 c, Mostly Clear at Singapore, Singapore

  /weatherdata:
    get:
      tags:
        - Weather Forecast
      summary: getWeatherData
      description: Get weather forecast with lots of details
      operationId: GetWeatherData
      externalDocs:
        description: More details
        url: "https://market.mashape.com/fyhao/weather-13#weatherdata"
      parameters:
        - $ref: '#/components/parameters/latParam'
        - $ref: '#/components/parameters/lngParam'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Successful operation
                $ref: '#/components/schemas/WeatherdataResponse'

Now we’re not repeating the parameter information multiple times. Instead, in components, we define these parameters:

components:
  parameters:
  - name: lat
    in: query
    description: "Latitude coordinates."
    required: true
    style: form
    explode: false
    schema:
      type: string
    example: "37.3708698"

  - name: lng
    in: query
    description: "Longitude coordinates."
    required: true
    style: form
    explode: false
    schema:
      type: string
    example: "-122.037593"

See Storing re-used parameters in components for more details. Also see Describing Parameters in Swagger’s OpenAPI documentation.

Appearance of paths in Swagger UI

Swagger UI displays the paths object like this:

When you click Try it out, the example value populates the parameters field.

Each path is collapsed by default, but you can set whether the initial display is collapsed or open using the docExpansion parameter in Swagger UI.

This docExpansion parameter is for Swagger UI and isn’t part of the OpenAPI spec. Swagger UI has more than 20 different parameters that control its display. Currently, there isn’t a parameter to hide the Models section or to disable the Try It Out section, but you can hide these functions through display: none with CSS, targeting the elements you want to hide. Additional Swagger UI parameters may be added in the future.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285