Quartz 4

Swagger

3 min read

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well, by reading your API’s structure, we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire API.^[What is Swagger | Swagger Docs]

Swagger provides a set of tools that help developers create, maintain, and visualize API documentation. The key components are:

  1. Swagger Editor: A web-based editor that allows you to write API specifications in the OpenAPI format (formerly known as Swagger in Version 2.0 and renamed as OpenAPI in Version 3.0). This format uses YAML or JSON to define the structure and functionality of an API.
  2. Swagger UI: A web-based user interface that can dynamically generate documentation from an OpenAPI specification. This allows developers to explore and test the API directly within the browser.
  3. Swagger Codegen: A tool that can generate client code in various programming languages (e.g., JavaScript, Python, Java, C#) from an OpenAPI specification. This helps speed up the process of integrating with an API.
  4. OpenAPI Specification: The underlying standard that defines the format for describing RESTful APIs. The OpenAPI Specification (formerly known as the Swagger Specification) is a language-agnostic interface description for describing, producing, consuming, and visualizing RESTful web services.

Version 3.0

OpenAPI Specification

Previously known as Swagger Specification in Version 2.0, an OpenAPI Specification is a description format for RESTful APIs.

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

__

Version 2.0

Swagger Specification

swagger: "2.0"
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0
 
host: api.example.com
basePath: /v1
schemes:
  - https
 
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

An example of a Swagger specification for an API endpoint written in YAML

api tool

Graph View

Backlinks