What is Swagger?

Swagger (or Open API) is a specification and a set of tools for designing, building, documenting, and using RESTful web services.

Main components:

• OpenAPI Specification (OAS): A language-independent format for describing RESTful APIs in JSON or YAML. It describes available endpoints, parameters, responses, data schemas, authentication, and metadata.
• Swagger UI: A tool for visualizing and interactively engaging with the API described in the OpenAPI specification. It allows viewing documentation and executing requests directly from the browser.
• Swagger Codegen: A set of tools for automatically generating server-side code (stubs) and client SDKs based on the OpenAPI specification.

Advantages of using:

• Unified documentation: Creates a standardized and always up-to-date documentation for the API.
• Contract-driven development: Enables backend and frontend teams to work in parallel, agreeing on the API contract.
• Test automation: Used for automatic generation of API tests (e.g., with Swagger Inspector).
• API discovery: Simplifies finding and understanding available APIs in the system.

Example of a specification part in YAML:

openapi: 3.0.0
info:
  title: Simple API
  version: 1.0.0
paths:
  /items:
    get:
      summary: Get a list of items
      responses:
        '200':
          description: A list of items.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string