OAI, Swagger and the way to build your API's

There is an evolving and trending tool called swagger, which is a simple yet powerful representation of your RESTful API, With the largest ecosystem of API tooling on the planet!

If you are asking whether this tool is promising, Well linux foundation who took the lead on the open API initiative (OAI), consider swagger 2.0 Spec to be the base for it and is going to extend it, this is a serious decision (see here)

This means that when using that specification to describe your API, you get the advantage of the following for free!!!:

• Generate your server code
• Generate your client SDK code (multiple languages of course) - Increase adoption of your service
• Full blown editor for your API's specifications, lets call this the architects whiteboard (it also has tools embedded in it)
• Generate online documentation for your API
• Many services already support automatically integrating with API that expose this specification (e.g. Camel and other)

Cool ha ? (this is a time saver and a serious easy-to-do-business factor)

There are couple of ways you can start 

1. Top down - You start with describing your API and than generating using the above
2. Bottom up - You already have your API, so either you use some tools to generate the specification or build it based on your API and than use the tools

Below is an example of little PET API: (no additional explanation needed)

swagger: '2.0'

info:

  version: 1.0.0

  title: Swagger Petstore (Simple)

  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification

  termsOfService: 'http://helloreverb.com/terms/'

  contact:

    name: Swagger API team

    email: foo@example.com

    url: 'http://swagger.io'

  license:

    name: MIT

    url: 'http://opensource.org/licenses/MIT'

host: petstore.swagger.io

basePath: /api

schemes:

  - http

consumes:

  - application/json

produces:

  - application/json

paths:

  /pets:

    get:

      description: Returns all pets from the system that the user has access to

      operationId: findPets

      produces:

        - application/json

        - application/xml

        - text/xml

        - text/html

      parameters:

        - name: tags

          in: query

          description: tags to filter by

          required: false

          type: array

          items:

            type: string

          collectionFormat: csv

        - name: limit

          in: query

          description: maximum number of results to return

          required: false

          type: integer

          format: int32

      responses:

        '200':

          description: pet response

          schema:

            type: array

            items:

              $ref: '#/definitions/pet'

        default:

          description: unexpected error

          schema:

            $ref: '#/definitions/errorModel'

  '/pets/{id}':

    get:

      description: 'Returns a user based on a single ID, if the user does not have access to the pet'

      operationId: findPetById

      produces:

        - application/json

        - application/xml

        - text/xml

        - text/html

      parameters:

        - name: id

          in: path

          description: ID of pet to fetch

          required: true

          type: integer

          format: int64

      responses:

        '200':

          description: pet response

          schema:

            $ref: '#/definitions/pet'

definitions:

  pet:

    type: object

    required:

      - id

      - name

    properties:

      id:

        type: integer

        format: int64

      name:

        type: string

      tag:

        type: string


Thanks snow-mirror for the image