Swagger Core Components

Swagger is an open-source toolset built around the OpenAPI Specification, used to design, build, document, and use RESTful APIs.

Swagger provides a standardized way to describe the structure of APIs, enabling both developers and machines to understand the functionality of an API without accessing source code or other documentation.

Swagger's core values are:

  • Standardization: Provides a unified API description format
  • Visualization: Automatically generates interactive API documentation
  • Testability: Allows testing API endpoints directly in the documentation
  • Code Generation: Supports client-side and server-side code generation in multiple languages

Swagger Core Components

ComponentInputOutputApplicable Stage
Swagger EditorManually write YAML/JSONAPI documentation with real-time previewAPI design stage
Swagger UIOpenAPI fileInteractive web documentationDevelopment/testing stage
Swagger CodegenOpenAPI fileClient/server codeFrontend-backend collaboration stage

Component collaboration flowchart:

Swagger Editor（设计API）  
  ↓  
OpenAPI 规范文件（YAML/JSON）  
  ↓  
Swagger UI（展示文档） 或 Swagger Codegen（生成代码）

Swagger Core Components Explained

1. Swagger Editor

Swagger Editor is a browser-based visual editor for writing and previewing OpenAPI specifications (YAML/JSON format) in real time.

Swagger Editor provides syntax highlighting, auto-completion, and error validation.

Swagger Editor's code generation, saving, and export features have now been integrated into SmartBear API Hub. Access address:https://try.platform.smartbear.com/new-organization。

Use cases:

  • Quickly design API prototypes
  • Learn OpenAPI specification syntax

Access the online editor Swagger Editor:https://editor.swagger.io/

Enter the following YAML code (defines a simple GET /users endpoint):

Example

span style="color: green;">
openapi: 3.0.3
info:
  title: EXAMPLE User Management System
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get user list
      responses:
        '200':
          description: Successfully returns user list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

The right side will render the API documentation and interactive UI in real time.

Swagger UI

Swagger UI converts OpenAPI specifications into visual interactive documentation and supports testing APIs directly in the browser.

Swagger UI automatically generates request examples, response models, and a debugging interface.

Swagger UI: https://swagger.io/tools/swagger-ui/

Use cases:

  • Share API documentation within a team
  • Frontend developers debug APIs

Integration example (using Node.js), install dependencies:

npm install swagger-ui-express swagger-jsdoc

Create a swagger.js configuration file:

Example

const swaggerJSDoc = require('swagger-jsdoc');
const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'User API', version: '1.0.0' },
  },
  apis: ['./routes/*.js'], // Scan comments in route files
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;

Mount UI in Express:

Example

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Visit http://localhost:3000/api-docs to view the documentation.

Swagger Codegen

Swagger Codegen automatically generates client SDKs (e.g., Java, Python) or server stub code (e.g., Spring, Flask) based on OpenAPI specifications.

Swagger Codegen supports custom templates.

Download page:https://swagger.io/tools/swagger-codegen/

Use cases:

  • Quickly generate client code for API calls
  • Automated development of server-side interfaces

Operation example (generate Java client via command line), download Swagger Codegen CLI:

wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar

Generate code:

java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l java \
  -o ./petstore-api-client

Swagger Hub (Optional Extension)

Swagger Hub is Swagger's cloud platform, providing collaborative design, version management, and hosted documentation.

Swagger Hub supports team collaboration and API lifecycle management.

Use cases:

  • Enterprise-level API project management
  • Distributed teams that need online collaboration

Access address:https://swagger.io/api-hub/

Other extensions