Swagger and OAS

 What is OAS?

Open API Specification is a specification for how to create an API definition file. You can use one of two structured data formats: YAML or JSON.

What is difference between YAML and JSON?

• In JSON, strings have quotes around them. In case of YAML, if you want to treat any number as string, put quotes around it.
• YAML indents are like JSON curly brackets { }
• YAML lists are like JSON arrays [ ]
• YAML is easier to read and write

What is Swagger?

It is a collection of tools that use the Open API Specification. Swagger uses YAML as the default.

Swagger Editor: Helps you write OAS files

Swagger CodeGen: Generates code in popular languages for using your API

Swagger UI: Generates documentation from OAS files

SwaggerHub: Hosted platform for designing and documenting APIs

How to write OAS file?

# Every Open API file needs this

swagger: "2.0"

#This is your document metadata

info:

  description: Sample API

  version: 0.1.0

  title: Sample API

#define Server Location

host: api.example.com

basePath: /v1

# Possible Schemes - https or http

schemes:

- https

- http

# define request (consumes) and response (produces) data format

consumes:

- application/json

produces:

- application/json

# URL endpoint with HTTP method and its response

paths:

  /results:

    get:

      description: get Results for all Students

      operationId: getResults

      parameters:

      - in: query

        name: class

        type: string

        required: false

      responses:

        200:

          description: successful

          schema:

            type: array

            items:

              $ref: "#/definitions/results"

# define security key

         security:

       - oauthExamPortal:

          - read:results

# Define security

securityDefinitions:

  oauthExamPortal:

    type: "oauth2"

    authorizationUrl: "https://dev.examportal.com/oauth/authenticate"

    flow: "implicit"

    scopes:

      write:results: Pubhlish results

      read:results: View results

#Define Structure for Result

definitions:

  results:

    type: object

    properties:

      id:

        type: integer

      name:

        type: string

      totalmarks:

        type: integer

Important Points for OAS:

1. There are generally 5 type of parameters in any request - in: query (for Query Paramaters), in: path (for URI parameters), in: header (for custom headers), in: body (for body), in: formData (for Form Data). For Form Data, generally, the type should be file.
2. Security options - none/basic/api key/oauth
3. You can use Markdown for description.
4. $ref is a special OAS key that indicates that the value is a reference to a structure somewhere else in the YAML file
5. In case of array, use type: array and add a key named items.
6. use the allOf key to resue existing object structure into another object.