10 points to consider when using Open API Specification 3 to document your REST API

Recently I've taken the time to update the API documentation for bookmarks.dev-api. I used Swagger 2.0 (aka OAS 2) before and I decided to update to OpenAPI Specification (OAS) 3. In this post I will list the main points about the process and documenting the API with OAS 3. Some points might still apply to the former OAS 2 (fka Swagger) documentation, but they are worth mentioning since I hadn't payed enough attention before to them.

The code snippets examples presented in this article are from the OAS 3 specification for bookmarks.dev-api, which is available on Github at openapi.yaml. The result is available at bookmarks.dev/api/docs/

Here are the ten points to consider:

1. Read the A Guide to What’s New in OpenAPI 3.0 article

In this article, they share some of the major updates in the latest version of OAS, and breakdown what you need to know when transitioning to OAS 3.0. It's based on this webinar OpenAPI 3.0, And What it Means for the Future of Swagger - 1 hour long

2. Use the OpenAPI/Swagger 2.0 to OpenAPI 3.0 Converter WebService

to convert your Swagger specification to OpenAPI 3.0.

It is available online at https://converter.swagger.io/ and as a docker image:

docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2

3. Use Swagger-Editor to immediate validate your specification and preview it in real time

Swagger Editor lets you edit Swagger API specifications in YAML inside your browser and to preview documentations in real time.

You can use it online, as an npm distribution or as a docker image.
For more details check the Readme of the project.

4. Use Swagger UI to present your documentation

Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

I use it indirectly with the help of Swagger UI Express. That way you can access the Swagger UI documentation as a route in the API for example, in my case at bookmarks.dev/api/docs/

The code snippet from app.js:

const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');

app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

It's helpful to include the open specification file (here openapi.yaml) in the nodemon watch (e.g. nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml), so that you can reload the UI without having to manually restart the ExpressJS server

4.1 Use swagger-jsdoc for a code-first approach

Another point worth mentioning here is that you could use swagger-jsdoc,
to integrate Swagger using JSDoc comments in your code. The swagger-jsdoc project assumes that you want document your existing/living/working code in a way to "give life" to it, generating a specification which can then be fed into other Swagger tools, and not the vice-versa.

For now I manage documentation centrally in one openapi.yaml file, but I might consider it at a later time

5. Use tags to group the operations

You can assign a list of tags to each API operation. Thus Swagger UI and Swagger Editor will display the operations by
tags which comes very handy. To control the sorting in Swagger UI you need to add them also at the root level as global
tags. There you can also add a description and link to external documentation for them.

Here are the tags I use for the API for

tags:
  - name: root
    description: Used to mark the root endpoint
  - name: version
    description: Access to the project's version and gitSha1
  - name: public-bookmarks
    description: Access to public bookmarks
  - name: personal-bookmarks
    description: Operations performed on personal bookmarks
  - name: user-data
    description: Operations performed on user data
  - name: helper
    description: Helper endpoints/operations

6. Use the servers array to specify one or more base URLs for your API

In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0. Each server has an url and an optional Markdown-formatted description.

servers:
  - url: http://localhost:3000/api
    description: Local server for development
  - url: https://www.bookmarks.dev/api
    description: Main (production) server

7. Use components in order to define and reuse resources

Often, multiple API operations have some common parameters or return the same response structure. To avoid code duplication, you can place the common definitions in the global components section and reference them using $ref.

For example for a list of bookmarks response that occurs with several operations I defined a BookmarkListResponse under the global responses section

components:
  responses:
    BookmarkListResponse:
      description: List of bookmarks
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Bookmark'

and I reference it in the different operations (e.g. get-public-bookmarks):

  /public/bookmarks:
    get:
      summary: Returns list of public bookmarks filtered with query parameters.
      tags:
        - public-bookmarks
      description: |
        * if `q` param is present they are filtered by the query text contained in it. (takes precedence over `location`)
        * if `location` param is present returns a list with one **public** bookmark with that URL
        * else **defaults** to the latest added 100 public bookmarks

        > The list is empty if not public bookmarks returned for filter
      parameters:
        - $ref: "#/components/parameters/searchTextQueryParam"
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/locationQueryParam"
      responses:
        200:
          description: OK
          $ref: '#/components/responses/BookmarkListResponse'

Notice above also the locationQueryParam. It's a location query parameter defined in the components > parameters section and then referenced in multiple places in the API specification (one of them above):

componentes:
  parameters:
    locationQueryParam:
      name: location
      in: query
      description: location of the bookmark, usually an URL
      required: false
      schema:
        type: string

8. Add examples to make it clearer

You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way. For example, an API mocking tool can use sample values to generate mock requests. You can specify examples for objects, individual properties and operation parameters. To specify an example, you use the example or examples keys.

For example the search text used to filter bookmarks can have complex values, and what better ways to explain it than with some examples:

components:
  parameters:
    searchTextQueryParam:
      name: q
      in: query
      description: |
        search query (terms are separated by space). There are special filters available:
          * `lang:iso_language_code` - e.g. `lang:en` for English, `lang:es` for Spanish and `lang:de` for German bookmarks
          * `site:site_URL` - e.g. `site:codepedia.org` bookmarks only from website [www.codepedia.org](https://www.codepedia.org)
          * `userId:UUID-user` - to be used only when querying **public bookmarks** submitted by the user with  `userId`
          * `private:only` - makes sense **only** when used for querying **personal bookmarks**
      schema:
        type: string
      examples:       # Multiple examples
        german:
          value: 'lang:de'    
          summary: Will look only for bookmarks in German
        site:
          value: 'site:codepedia.org'
          summary: Wille look only for bookmarks with the domain **codepedia.org**
        complex:
          value: 'exception handling [java] site:codepedia.org'
          summary: Wille look only for bookmarks with terms "exception" and "handling" tagged with "java" and the domain **codepedia.org**
        complex-private-only:
          value: 'exception handling [java] site:wiki.my-corporation.com private:only'
          summary: Same as above but only within **private** bookmarks

or show what a bookmark input for creation might look like, for different scenarios (normal article, youtube video or StackOverflow question):

paths:
  /personal/users/{userId}/bookmarks:
    post:
      description: Create new bookmark for user
      operationId: create-bookmark
      tags:
        - personal-bookmarks
      parameters:
        - $ref: '#/components/parameters/userIdPathParam'
      requestBody:
        description: Bookmark json data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bookmark'
            examples:
              blog-article:
                value:
                  name: Cleaner code in an Express REST API with unified error handling – CodepediaOrg
                  location: https://www.codepedia.org/ama/cleaner-code-in-expressjs-rest-api-with-custom-error-handling
                  language: en
                  tags: [nodejs, error-handling, expressjs]
                  publishedOn: 2019-12-02,
                  sourceCodeURL: https://github.com/CodepediaOrg/bookmarks.dev-api
                  description: Shows how you can make your backend ExpressJS REST API cleaner by using custom error handling middleware. Code snippets of before and after refactoring are presented to make the point
                  descriptionHtml: <p>Shows how you can make your backend ExpressJS REST API cleaner by using custom error handling middleware. Code snippets of before and after refactoring are presented to make the point</p>
                  userId: 4c617f2b-2bad-498b-a9c6-4e9a8c303798
                  public: true,
                  lastAccessedAt: 2020-02-15T20:42:19.297Z
                  likeCount: 0
              stackoverflow-question:
                value:
                  name: Create GUID / UUID in JavaScript?
                  location: https://stackoverflow.com/questions/105034/create-guid-uuid-in-javascript
                  language: en
                  tags: [javascript, guid, uuid]
                  publishedOn: 2008-09-19
                  sourceCodeURL:
                  description: UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally Unique IDentifier), according to [RFC 4122](https://www.ietf.org/rfc/rfc4122.txt), are identifiers with a certain uniqueness guarantee.\n\nThe best way to generate them, is to follow implementation instructions in the said RFC, use one of the many community vetted open source implementations.\n\nA popular Open Source tool for working with UUIDs in JavaScript is [node-uuid](https://github.com/kelektiv/node-uuid)\n\nNote that just randomly generating the identifiers byte by byte, or character by character, will not give you the same guarantees as a conforming implementation. Also, very important, systems working with compliant UUIDs may choose not to accept randomly generated ones, and many open source validators will actually check for a valid structure.\n\nAn UUID must have this format:\n```
{% endraw %}
\nxxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx\n
{% raw %}
```\nWhere the M and N positions may only have certain values. At this time, the only valid values for M are 1, 2, 3, 4 and 5, so randomly generating that position would make most results unacceptable.
                  descriptionHtml: <p>UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally Unique IDentifier), according to <a href=\"https://www.ietf.org/rfc/rfc4122.txt\">RFC 4122</a>, are identifiers with a certain uniqueness guarantee.</p>\n<p>The best way to generate them, is to follow implementation instructions in the said RFC, use one of the many community vetted open source implementations.</p>\n<p>A popular Open Source tool for working with UUIDs in JavaScript is <a href=\"https://github.com/kelektiv/node-uuid\">node-uuid</a></p>\n<p>Note that just randomly generating the identifiers byte by byte, or character by character, will not give you the same guarantees as a conforming implementation. Also, very important, systems working with compliant UUIDs may choose not to accept randomly generated ones, and many open source validators will actually check for a valid structure.</p>\n<p>An UUID must have this format:</p>\n<pre><code>xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx\n</code></pre>\n<p>Where the M and N positions may only have certain values. At this time, the only valid values for M are 1, 2, 3, 4 and 5, so randomly generating that position would make most results unacceptable.</p>
                  userId: 4c617f2b-2bad-498b-a9c6-4e9a8c303798
                  public: true
                  lastAccessedAt: 2020-02-15T20:59:45.447Z
                  likeCount: 0
                  stackoverflowQuestionId: 105034
              youtube-video:
                value:
                  name: Jake Archibald In The Loop - JSConf.Asia - 35min
                  location: https://www.youtube.com/watch?v=cCOL7MC4Pl0
                  language: en
                  tags: [javascript, event-loop, browser]
                  publishedOn: 2018-02-09
                  sourceCodeURL:
                  description: Have you ever had a bug where things were happening in the wrong order, or particular style changes were being ignored? Ever fixed that bug by wrapping a section of code in a setTimeout? Ever found that fix to be unreliable, and played around with the timeout number until it kinda almost always worked? \nThis talk looks at the browser's event loop, the thing that orchestrates the main thread of the browser, which includes JavaScript, events, and rendering. We'll look at the difference between tasks, microtasks, requestAnimationFrame, requestIdleCallback, and where events land. \nHopefully you'll never have to use setTimeout hacks again!\"
                  descriptionHtml: <p>Have you ever had a bug where things were happening in the wrong order, or particular style changes were being ignored? Ever fixed that bug by wrapping a section of code in a setTimeout? Ever found that fix to be unreliable, and played around with the timeout number until it kinda almost always worked? \nThis talk looks at the browser's event loop, the thing that orchestrates the main thread of the browser, which includes JavaScript, events, and rendering. We'll look at the difference between tasks, microtasks, requestAnimationFrame, requestIdleCallback, and where events land. \nHopefully you'll never have to use setTimeout hacks again!\"</p>
                  userId: 4c617f2b-2bad-498b-a9c6-4e9a8c303798
                  public: true
                  lastAccessedAt: 2020-02-15T21:12:12.670Z
                  likeCount: 0
                  youtubeVideoId: cCOL7MC4Pl0

9. Use enums to define constants

Open API does not support the const keyword of JSON Schema yet
but you can use enum to define one value. For example I know that the validation errors have a HTTP Status of 400 (Bad request) so I can model this the following way:

components:
  schemas:
    ValidationErrorModel:
      allOf:
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          required:
            - validationErrors
            - httpStatus
          properties:
            httpStatus:
              type: integer
              enum: [400]
            validationErrors:
              type: array
              items:
                type: string

Of course you can use enums to specify values for a request parameter or a model property, as they were intended. For example see the orderBy possible values when filtering personal bookmarks

paths:
  /personal/users/{userId}/bookmarks:
    get:
      parameters:
        - $ref: "#/components/parameters/userIdPathParam"
        - $ref: "#/components/parameters/searchTextQueryParam"
        - $ref: "#/components/parameters/limitQueryParam"
        - $ref: "#/components/parameters/locationQueryParam"
        - name: orderBy
        in: query
          description: |
          It is considered in the abscence of `q` or `location` parameters
          Possible values:
            * MOST_LIKES - personal bookmarks most liked by the community
            * LAST_CREATED - personal bookmarks last added
            * MOST_USED - personal bookmarks the user (owner) clicked the most
          schema:
            type: string
            enum: [MOST_LIKES, LAST_CREATED, MOST_USED]

10. Bookmark the resources you might recall later

I have bookmarked quite a few Swagger/OpenAPI resources and tools along the way and made them public at my [openapi] public resources on bookmarks.dev

Conclusion

These were the ten points to remember when starting with OpenAPI Specification 3. Do you have others worth mentioning? Please leave a comment below with it if you do.