This blog post will cover everything you need to know about Swagger from an architectural point of view and a basics in-terms of development point of view in API Portal, Developer Portal and SwaggerHub:

• What is a Swagger?
• Environment Setup to develop a Swagger: Locally as well as in browser.
• Understanding a Swagger
• How to implement a Swagger in your API?
• How to deploy your Swagger?
• And modifying Swagger after API is deployed to production.

If you need to know where Swagger comes into picture and what else are present in SAP API Management…, then I would suggest you to start with my previoud blog post: Everything you need to know before Getting Started with SAP API Management

What is a Swagger?

Swagger(also known as OpenAPI Specification) is a industry standard for documenting an API. This document can be used to:

1. Provide the detailed understanding about the API’s developed.
2. And also, to directly validate your API requests based on it.

This post is mainly about how to develop the Swagger. I’ll try to do another blog post regarding API Validation based on Swagger.

Swagger can be developed by following either Swagger 2.0 Standards or Swagger 3.0 Standards.

For this tutorial, we will be following Swagger 2.0.

Environment Setup to develop a Swagger

Swagger can be developed in multiple places depending on your area of working:

• Sandbox on Cloud: To understand Swagger and trying to do some basic testings…, then you can use Swagger Editor. Here You can always develop a Swagger from Scratch.
• Personal Sandbox: To do the same in local environment, you can install Swagger from Docker:

  docker run -d -p 80:8080 swaggerapi/swagger-editor
  

  This provides the same Swagger Editor as earlier for local development.

• Business Use(Dev, Test and Prod Environments): So, once a swagger is developed using one of the above methods, you need to store the swagger and depending on the client’s requirement, you will have to modify it and version it going forward. So, for better maintainence and versioning: you can login and store your Swagger in Swagger Hub. Everyone can store upto 3 Swaggers of their own. Once Swagger is approved by a client, you will be developing API’s.
• Now, while developing API, we will be adding this swagger in our API Portal. Steps to add Swagger in your API Portal.
• And view it in our Developer Portal. The Swagger is not completely implemented in API Portal. So, I would suggest to show Swagger from SwaggerHub and Not from Developer Portal. Here, we will be showing it from Developer Portal as well in case you need for your usecase.

Understanding a Swagger

Swagger consists of

• Swagger Version: Ex: 2.0, 3.0.0, 3.0.3, etc..
• Basic Information: like the Title, Description, and Version of the API.
• Servers or the URLs that they can call to:
  • until Swagger 2.0: We only used to have one URL and two protocols: HTTP and HTTPS.
  • from Swagger 3.0: We are able to have multiple URL’s. In Developer terms, you can have multiple environment URLs: sandbox, dev, qa, perf, test, staging, prod, or any specific URLs you would like to mention…
• Tags to differentiate different endpoints inside the Swagger. Every Tag can have multiple API’s specific to it.
• Every endpoint will have:
  • Request Data Structure.
  • Response Data Structure.
  • Authentication to access it.
  • And an operationId: operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API. This is a crucial part of an API if you are validating your payload using Swagger.

With all the information above, I hope you can start diving deep into understanding and developing swagger.

How to implement a Swagger in your API?

For this tutorial, I will be using Swagger 2.0 sample provided by SwaggerHub. This is an API for petstore where when you trigger POST http://petstore.swagger.io/pet you can upload data of a pet. The following is a swagger file for this.

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
schemes:
- "https"
- "http"
paths:
  /pet:
    post:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
      responses:
        "405":
          description: "Invalid input"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"
securityDefinitions:
  petstore_auth:
    type: "oauth2"
    authorizationUrl: "http://petstore.swagger.io/oauth/dialog"
    flow: "implicit"
    scopes:
      write:pets: "modify pets in your account"
      read:pets: "read your pets"
  api_key:
    type: "apiKey"
    name: "api_key"
    in: "header"
definitions:
  Category:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
    xml:
      name: "Category"
  Tag:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
    xml:
      name: "Tag"
  Pet:
    type: "object"
    required:
    - "name"
    - "photoUrls"
    properties:
      id:
        type: "integer"
        format: "int64"
      category:
        $ref: "#/definitions/Category"
      name:
        type: "string"
        example: "doggie"
      photoUrls:
        type: "array"
        xml:
          name: "photoUrl"
          wrapped: true
        items:
          type: "string"
      tags:
        type: "array"
        xml:
          name: "tag"
          wrapped: true
        items:
          $ref: "#/definitions/Tag"
      status:
        type: "string"
        description: "pet status in the store"
        enum:
        - "available"
        - "pending"
        - "sold"
    xml:
      name: "Pet"
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"

You can copy and paste the above swagger to editor.swagger.io . And do some of your own editings as below:

Swagger Editor for developing a Swagger

Once it’s done, you need to upload the swagger to API Portal:

Create in API Designer

Paste the Swagger and Click on Save

You can login to Developer Portal and Register as Developers. You will be able to view your Swagger there. You can also view your Swagger in API Portal under Resources Tab.

Viewing Swagger in API Portal

Viewing Swagger from Client Perspective

Swagger can be viewed by Client in 3 different ways:

1. SwaggerHub URL generated for your swagger.
2. Developer Portal once your client is registered in the Portal.
3. Client Facing SDK: SwaggerHub and Developer Portal both provide a way to download the Swagger and upload it in any of your own Client’s Website.
   All you have to do is download it, unzip it and open Readme.md File. This provides step by step instructions based on which platform your Client is using. Example: Spring, NodeJS, JAX-RS, etc…

Swagger Changes after API is in Production.

Bases version of Swagger in SwaggerHub is 1.0.0 by default. So, Whenever there are bug fixes like Swagger request body, response body structure change, error message change, etc. Then, we will create a swagger with 1.0.1

When a client requests for a minor changes in API: like adding a new endpoint, adding a new environment, etc. Then, we should be using the second digit: 1.1.0.

If there are Major changes in an API, then we should be changing it to 2.0.0, 3.0.0, and so on…

Unlike SwaggerHub, API Portal maintains Swagger in a single digit versioning. So, Only when there is a major change in the API, a new API will be created.

This is one of the reasons why I suggest to use SwaggerHub as well as API Portal for maintaining Swagger. So, SwaggerHub can show every change that has happened till now. And API Portal will be showing the latest version of the API in every major version changes…

API Portal also provides the same versioning as above but versioning needs to be added in the API in order for it work.

Additionally, API Portal has API State for tracking the API’s during development: Beta, Alpha, Active, Deprecated and Decommissioned. So, As long as API is not finalized and there are bug fixes, then you can place API in Beta State. If the API is having minor changes, then you can place it in Alpha State. And when API is finalized, you can make it as Active. But again, after moving to production, if there are any bug fixes or minor changes to be done, it still cannot be tracked.

Conclusion

This blog post provides basics of Swagger and API Portal which can be helpful for developing a well architected API irrespective of the logic. This only provides documentation and how a document can be viewed in SAP API Management. Hope it helps you in your learning for SAP APIM.

Sai Sreenivas Addepalli.