Microservices

Introduction to OpenAPI

vasu34k

OpenAPI Specification also known as Swagger Specification is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

  • Available endpoints and operations on each endpoint (GET, POST)
  • Operation parameters Input and output for each operation
  • Authentication methods
  • Contact information, license, terms of use.

These API specifications can be written in YAML or JSON formats. These formats are interchangeable and include the same elements.

There are three primary areas in every OpenAPI document:

  • Endpoints (i.e. paths appended to the server URL) and the HTTP methods they support. For each method, any parameters that may or must be included in the request and the response formats for the possible HTTP response codes are specified.
  • Reusable components that can be used across multiple endpoints in the API, such as common request parameters and response formats.
  • Meta information, including the title, version, and description of the API, authentication method, and location of the API servers.

Swagger is a tool that is used to implement Open API specification.It is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

openapi

The major Swagger tools include:

  • Swagger Editor – browser-based editor where you can write OpenAPI definitions.
  • Swagger UI – renders OpenAPI definitions as interactive documentation.
  • Swagger Codegen – generates server stubs and client libraries from an OpenAPI definition.
  • Swagger Editor Next (beta) – browser-based editor where you can write and review OpenAPI and AsyncAPI definitions.
  • Swagger Core – Java-related libraries for creating, consuming, and working with OpenAPI definitions.
  • Swagger Parser – standalone library for parsing OpenAPI definitions
  • Swagger APIDom – provides a single, unifying structure for describing APIs across various description languages and serialization formats.

Basic Structure

You can write OpenAPI definitions in YAML or JSON. Below is Sample OpenAPI 3.0 definition written in YAML looks like:

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

Note: All keywords are case sensitive.

Loading

Translate »