4. OpenAPI/Swagger 规范入门：OpenAPI 3.0 核心结构

OpenAPI 规范（原 Swagger 规范）是业界标准的 RESTful API 接口描述语言。OpenAPI 3.0 版本通过一套结构化的 JSON 或 YAML 文档，完整定义 API 的端点、请求参数、响应格式、认证方式及数据模型。在 Go 后端项目中，使用 OpenAPI 规范作为接口契约，可以实现前后端并行开发、自动化测试与文档生成。

4.1 OpenAPI 3.0 文档顶层结构

一个合法的 OpenAPI 3.0 文档必须包含以下四个顶层字段：openapi、info、paths 和 components。其余字段如 servers、tags、externalDocs 为可选增强。

4.2 Info 对象：API 元信息

info 对象提供 API 的基本标识和文档说明。Go 后端团队在发布接口契约时，应在此字段中明确 API 名称、版本号以及维护团队的联系方式。

info:
  title: "用户服务 API"
  description: "提供用户注册、登录、资料查询与修改功能"
  version: "1.0.0"
  contact:
    name: "后端架构组"
    email: "backend@example.com"
  license:
    name: "Apache 2.0"
    url: "https://www.apache.org/licenses/LICENSE-2.0"

4.3 Paths 对象：端点与操作

paths 是 OpenAPI 文档的核心，以 URL 路径为键，映射该路径下支持的 HTTP 方法（GET、POST、PUT、DELETE 等）。每个操作（Operation Object）包含 parameters、requestBody、responses 等子字段。

paths:
  /users:
    get:
      summary: "获取用户列表"
      operationId: "listUsers"
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: "用户列表"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: "创建新用户"
      operationId: "createUser"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

4.4 Components 对象：可复用定义

components 是 OpenAPI 3.0 的复用中心，包含 schemas、parameters、responses、requestBodies、securitySchemes 等子对象。Go 后端团队在此定义数据模型，与 Go 结构体一一对应。

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: integer
          format: int64
        email:
          type: string
          format: email
        nickname:
          type: string
        created_at:
          type: string
          format: date-time
    CreateUserRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        nickname:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

4.5 OpenAPI 3.0 文档结构总览

下图展示了 OpenAPI 3.0 文档的顶层结构以及各核心对象之间的引用关系。Go 后端开发者应重点关注 paths 与 components/schemas 之间的 $ref 连接。

4.6 从 Go 结构体到 OpenAPI Schema 的映射规则

在 Go 后端项目中，OpenAPI 的 components/schemas 与 Go 结构体之间存在直接映射关系。下表列出常见 Go 类型与 OpenAPI 类型的对应关系：

4.7 最小可用 OpenAPI 3.0 文档示例

以下是一个完整的 OpenAPI 3.0 文档，包含 info、paths 和 components 三个核心部分。Go 后端团队可以以此作为起点，逐步扩展接口定义。

openapi: "3.0.3"
info:
  title: "订单服务 API"
  version: "1.0.0"
  description: "提供订单创建、查询与状态更新接口"
paths:
  /orders:
    get:
      operationId: "listOrders"
      summary: "查询订单列表"
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, paid, shipped, cancelled]
      responses:
        "200":
          description: "订单列表"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
    post:
      operationId: "createOrder"
      summary: "创建新订单"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderRequest"
      responses:
        "201":
          description: "创建成功"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
components:
  schemas:
    Order:
      type: object
      required: [id, user_id, total_amount, status]
      properties:
        id:
          type: integer
          format: int64
        user_id:
          type: integer
          format: int64
        total_amount:
          type: number
          format: double
        status:
          type: string
          enum: [pending, paid, shipped, cancelled]
        created_at:
          type: string
          format: date-time
    CreateOrderRequest:
      type: object
      required: [user_id, items]
      properties:
        user_id:
          type: integer
          format: int64
        items:
          type: array
          items:
            type: object
            required: [product_id, quantity]
            properties:
              product_id:
                type: integer
                format: int64
              quantity:
                type: integer
                minimum: 1