文档与工具

这一课你将能做到

1. 用 OpenAPI 3.0 规范手写或生成 API 文档，并集成 Swagger UI
2. 使用 Postman 进行 API 测试、Mock 和自动化监控
3. 建立 API 设计评审流程，用 Stoplight 或类似工具做版本管理和风格统一

为什么要学

代码会过时，文档才是 API 的长期契约。好的文档让前端「自助接入」，不用反复问后端；好的工具链让设计、开发、测试、发布形成闭环。面试常问：怎么管理 API 文档？怎么做 API 评审？

先建立图像

API 文档工作流：

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  设计     │──►│  评审     │──►│  开发     │──►│  发布     │
│ OpenAPI  │   │ Stoplight │   │ 代码生成  │   │ Swagger   │
│  YAML    │   │  风格检查  │   │ Mock 服务 │   │  UI 文档  │
└──────────┘   └──────────┘   └──────────┘   └──────────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
  契约优先      统一风格       前后端并行      在线文档
  版本管理      命名规范       Mock 联调      实时更新

跟着做

步骤 1：手写 OpenAPI 3.0 规范

# openapi.yaml
openapi: 3.0.3
info:
  title: CodeForge API
  description: 编程学习平台 API 文档
  version: 1.0.0
  contact:
    name: CodeForge Team
    email: api@codeforge.com

servers:
  - url: http://localhost:8080/api
    description: 本地开发
  - url: https://api.codeforge.com/api
    description: 生产环境

tags:
  - name: lessons
    description: 课程管理

paths:
  /lessons:
    get:
      tags:
        - lessons
      summary: 获取课程列表
      description: 分页查询所有课程，支持按学习路径过滤
      operationId: listLessons
      parameters:
        - name: page
          in: query
          description: 页码（0-based）
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          description: 每页大小
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: trackId
          in: query
          description: 学习路径 ID
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponsePageLesson'
        '400':
          description: 参数错误
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'

    post:
      tags:
        - lessons
      summary: 创建课程
      description: 管理员创建新课程
      operationId: createLesson
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LessonRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseLesson'
        '403':
          description: 无权限
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'

  /lessons/{id}:
    get:
      tags:
        - lessons
      summary: 获取课程详情
      operationId: getLesson
      parameters:
        - name: id
          in: path
          required: true
          description: 课程 ID
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseLesson'
        '404':
          description: 课程不存在
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Lesson:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        title:
          type: string
          example: Spring Boot 入门
        slug:
          type: string
          example: spring-boot-intro
        content:
          type: string
        trackId:
          type: string
          example: java-web
        createdAt:
          type: string
          format: date-time

    LessonRequest:
      type: object
      required:
        - title
        - slug
        - trackId
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 100
        slug:
          type: string
          pattern: '^[a-z0-9-]+$'
        trackId:
          type: string
        content:
          type: string

    ApiResponseLesson:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/Lesson'

    ApiResponsePageLesson:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          type: object
          properties:
            content:
              type: array
              items:
                $ref: '#/components/schemas/Lesson'
            page:
              type: integer
            size:
              type: integer
            totalElements:
              type: integer
            totalPages:
              type: integer

    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri