openapi-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAPI Expert

OpenAPI专家指南

Expert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.

为OpenAPI规范（前身为Swagger）提供专业指导——这是用于描述RESTful API的行业标准，支持自动文档生成和代码生成。

Core Concepts

核心概念

OpenAPI Specification (OAS)

OpenAPI规范（OAS）

API description format (YAML/JSON)
Version 3.1 (latest) and 3.0
Machine-readable API contracts
Automatic documentation generation
Client/server code generation
API validation and testing

API描述格式（YAML/JSON）
版本3.1（最新版）和3.0
机器可读的API契约
自动文档生成
客户端/服务端代码生成
API验证与测试

Key Components

核心组件

Paths (endpoints)
Operations (HTTP methods)
Parameters
Request/Response bodies
Schemas (data models)
Security schemes
Components (reusable objects)

Paths（端点）
Operations（HTTP方法）
参数
请求/响应体
Schemas（数据模型）
安全方案
Components（可复用对象）

Basic OpenAPI Specification

基础OpenAPI规范

yaml

openapi: 3.1.0
info:
  title: Blog API
  description: RESTful API for blog management
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /posts:
    get:
      summary: List all posts
      description: Returns a paginated list of blog posts
      operationId: listPosts
      tags:
        - Posts
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, published]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      summary: Create a new post
      operationId: createPost
      tags:
        - Posts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreate'
      responses:
        '201':
          description: Post created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

  /posts/{postId}:
    parameters:
      - name: postId
        in: path
        required: true
        description: Post ID
        schema:
          type: integer
          format: int64

    get:
      summary: Get a post
      operationId: getPost
      tags:
        - Posts
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Update a post
      operationId: updatePost
      tags:
        - Posts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUpdate'
      responses:
        '200':
          description: Post updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete a post
      operationId: deletePost
      tags:
        - Posts
      security:
        - bearerAuth: []
      responses:
        '204':
          description: Post deleted
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    Post:
      type: object
      required:
        - id
        - title
        - content
        - author
        - status
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        title:
          type: string
          minLength: 5
          maxLength: 200
        slug:
          type: string
          readOnly: true
        content:
          type: string
          minLength: 10
        author:
          $ref: '#/components/schemas/User'
        status:
          type: string
          enum: [draft, published]
          default: draft
        tags:
          type: array
          items:
            type: string
          maxItems: 10
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    PostCreate:
      type: object
      required:
        - title
        - content
      properties:
        title:
          type: string
          minLength: 5
          maxLength: 200
        content:
          type: string
          minLength: 10
        status:
          type: string
          enum: [draft, published]
          default: draft
        tags:
          type: array
          items:
            type: string

    PostUpdate:
      type: object
      properties:
        title:
          type: string
          minLength: 5
          maxLength: 200
        content:
          type: string
          minLength: 10
        status:
          type: string
          enum: [draft, published]
        tags:
          type: array
          items:
            type: string

    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        email:
          type: string
          format: email
        name:
          type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - bearerAuth: []

yaml

openapi: 3.1.0
info:
  title: Blog API
  description: RESTful API for blog management
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /posts:
    get:
      summary: List all posts
      description: Returns a paginated list of blog posts
      operationId: listPosts
      tags:
        - Posts
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, published]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Post'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

    post:
      summary: Create a new post
      operationId: createPost
      tags:
        - Posts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreate'
      responses:
        '201':
          description: Post created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

  /posts/{postId}:
    parameters:
      - name: postId
        in: path
        required: true
        description: Post ID
        schema:
          type: integer
          format: int64

    get:
      summary: Get a post
      operationId: getPost
      tags:
        - Posts
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Update a post
      operationId: updatePost
      tags:
        - Posts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUpdate'
      responses:
        '200':
          description: Post updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete a post
      operationId: deletePost
      tags:
        - Posts
      security:
        - bearerAuth: []
      responses:
        '204':
          description: Post deleted
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    Post:
      type: object
      required:
        - id
        - title
        - content
        - author
        - status
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        title:
          type: string
          minLength: 5
          maxLength: 200
        slug:
          type: string
          readOnly: true
        content:
          type: string
          minLength: 10
        author:
          $ref: '#/components/schemas/User'
        status:
          type: string
          enum: [draft, published]
          default: draft
        tags:
          type: array
          items:
            type: string
          maxItems: 10
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

    PostCreate:
      type: object
      required:
        - title
        - content
      properties:
        title:
          type: string
          minLength: 5
          maxLength: 200
        content:
          type: string
          minLength: 10
        status:
          type: string
          enum: [draft, published]
          default: draft
        tags:
          type: array
          items:
            type: string

    PostUpdate:
      type: object
      properties:
        title:
          type: string
          minLength: 5
          maxLength: 200
        content:
          type: string
          minLength: 10
        status:
          type: string
          enum: [draft, published]
        tags:
          type: array
          items:
            type: string

    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        email:
          type: string
          format: email
        name:
          type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - bearerAuth: []

Advanced Features

高级特性

Webhooks (OpenAPI 3.1)

Webhooks（OpenAPI 3.1）

yaml

webhooks:
  postCreated:
    post:
      summary: Post created webhook
      operationId: onPostCreated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Webhook received

yaml

webhooks:
  postCreated:
    post:
      summary: Post created webhook
      operationId: onPostCreated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Webhook received

Polymorphism (oneOf/anyOf/allOf)

多态性（oneOf/anyOf/allOf）

yaml

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

    Cat:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [cat]
            meow:
              type: string

    Dog:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [dog]
            bark:
              type: string

yaml

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

    Cat:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [cat]
            meow:
              type: string

    Dog:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [dog]
            bark:
              type: string

Code Generation

代码生成

bash

undefined

bash

undefined

Install OpenAPI Generator

npm install -g @openapitools/openapi-generator-cli

Generate TypeScript client

openapi-generator-cli generate
-i openapi.yaml
-g typescript-axios
-o ./client

Generate Python Flask server

openapi-generator-cli generate
-i openapi.yaml
-g python-flask
-o ./server

Generate Java Spring server

openapi-generator-cli generate
-i openapi.yaml
-g spring
-o ./server

undefined

openapi-generator-cli generate
-i openapi.yaml
-g spring
-o ./server

undefined

Validation

验证

bash

undefined

bash

undefined

Install Spectral (OpenAPI linter)

npm install -g @stoplight/spectral-cli

Validate spec

spectral lint openapi.yaml

Custom ruleset

.spectral.yaml

extends: spectral:oas rules: operation-tags: error operation-operationId: error no-$ref-siblings: error

undefined

extends: spectral:oas rules: operation-tags: error operation-operationId: error no-$ref-siblings: error

undefined

Documentation Generation

文档生成

bash

undefined

bash

undefined

Swagger UI

docker run -p 8080:8080
-e SWAGGER_JSON=/openapi.yaml
-v $(pwd):/usr/share/nginx/html
swaggerapi/swagger-ui

Redoc

docker run -p 8080:80
-e SPEC_URL=openapi.yaml
-v $(pwd):/usr/share/nginx/html
redocly/redoc

undefined

docker run -p 8080:80
-e SPEC_URL=openapi.yaml
-v $(pwd):/usr/share/nginx/html
redocly/redoc

undefined

Best Practices

最佳实践

Use semantic versioning
Include examples in schemas
Provide clear descriptions
Use components for reusability
Define proper error responses
Include security schemes
Add operation IDs
Tag operations logically
Validate specifications
Version your APIs

使用语义化版本控制
在Schemas中包含示例
提供清晰的描述
使用Components实现复用
定义规范的错误响应
包含安全方案
添加操作ID
对操作进行逻辑分组打标签
验证规范
对API进行版本控制

Resources

资源

OpenAPI Spec: https://spec.openapis.org/
Swagger Editor: https://editor.swagger.io/
OpenAPI Tools: https://openapi.tools/
Stoplight Studio: https://stoplight.io/studio

OpenAPI规范官网：https://spec.openapis.org/
Swagger编辑器：https://editor.swagger.io/
OpenAPI工具集：https://openapi.tools/
Stoplight Studio：https://stoplight.io/studio