Swagger, The OpenAPI specification, and You

One of the nice things about computer science is our devotion to accurate names. Clear, consistent terminology ensures that when we’re talking about something, we’re all talking about the same thing. Except when the terminology changes on us, and everyone has to get used to some new names.

You’ve probably heard the term “Swagger”.  The name originally referred to a project that defines a standard for RESTful API specifications. With a formal, computer-readable API specification, you can easily generate documentation or SDKs in several different languages. Swagger’s specification quickly attracted widespread industry interest and use, and a few years ago was reorganized under the Linux Foundation.

At that time, the Swagger project was renamed to more accurately suggest what it is. For the last few years, the proper name for the project formerly known as Swagger is “The OpenAPI Specification”. Unfortunately, the name “Swagger” wasn’t deprecated and discarded. Instead, the powers-that-be rebranded the various software tools that support SDKs, document generation, and editing as “Swagger”.

You’ll still hear the name “Swagger”, but in many cases, what people are talking about, and should be calling it, is the vendor-neutral “OpenAPI Specification”, or “OAS”.

Writing an OpenAPI Specification

Now we’ve cleared that up, let’s take a quick look at how you write an OpenAPI specification.

The specification will be a UTF-8 YAML or JSON file that contains all the information about your API, including:

• The endpoints you can call, and the HTTP methods they support (GET, POST, etc…)
• The request parameters you pass into a call, and the response data you get back as an HTTP body
• The authentication approach to use
• A description of what each call does and how developers can use them
• License terms and other administrative details

The Envestnet | Yodlee OpenAPI specification is available on GitHub. You can download it and see how Envestnet | Yodlee’s APIs are described. We wrote these back when the specification was still called Swagger, so the file is called “swagger.yaml”. If we were writing it today, we would name the file “OpenAPI.yaml”.

Here’s an extract from Envestnet | Yodlee’s swagger.yaml, lightly edited for clarity. This extract specifies the first call your app will make to the Envestnet | Yodlee API – the call to request an authentication token permitting further calls.

/auth/token:
    post:
      summary: "Generate Access Token"
      produces:
      - "application/json;charset=UTF-8"
      description: "Generate Access Token using client credential
                   authentication. This service returns tokens 
                   required to access Yodlee 1.1 APIs”
      operationId: "generateAccessToken"
      responses:
        201:
          schema:
            $ref: "#/definitions/ClientCredentialTokenResponse"
          description: "the OK response"

The “description” field supports documentation generated from the OpenAPI file. Our file was written to version 2 of the standard. Version 3 of the standard requires descriptions to use the CommonMark dialect of Markdown. The API documentation on our API reference page is generated from this file. Developers can write some English sentences describing what an API call does, in the same place where they define the API call.

Later in the file, you will find the ClientCredentialTokenResponse HTTP body. It contains a ClientCredentialToken that looks like this:

ClientCredentialToken:
    type: "object"
    title: "ClientCredentialToken"
    properties:
      expiresIn:
        format: "int32"
        description: "Time in seconds after which the issued 
                      accessToken expires.
                      Endpoints:
                         POST /auth/token"
        readOnly: true
        type: "integer"
      issuedAt:
        description: "The date and time on which accessToken 
                     was created for the customer.
                     Endpoints:
                     POST /auth/token"
        readOnly: true
        type: "string"
      accessToken:
        description: "Access Token to access YSL 1.1
                     services.  Endpoints:
                     POST /auth/token"
        readOnly: true
        type: "string"

The OpenAPI specification was an important milestone in cementing RESTful APIs as the most popular software architecture for communicating with a computer. It displaced older approaches like SOAP and CORBA.

You can read more about using YAML here. YAML is more concise than JSON, but JSON is widely used for more and additional purposes in software. You can also find a good tutorial on the whole OpenAPI toolset here. Finally, visit the OpenAPI Specification homepage here.