OpenAPI 规范基础

顶层结构

YAML

openapi: 3.0.3            # 规范版本，必填
info:                     # 元信息，必填
  title: User API
  version: 1.0.0
  description: 用户服务接口
servers:                  # 服务器列表
  - url: https://api.example.com/v1
    description: 生产
  - url: http://localhost:8080/v1
    description: 本地
paths:                    # 路径与操作，必填
  /users:
    get: { ... }
    post: { ... }
components:               # 可复用组件
  schemas: { ... }
  parameters: { ... }
  responses: { ... }
  securitySchemes: { ... }

paths 与 operation

Keys under paths are path templates; values hold HTTP methods. Every operation needs responses and usually summary, parameters, requestBody, tags.

YAML

paths:
  /users/{id}:
    get:
      tags: [Users]
      summary: 查询单个用户
      operationId: getUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components 与 $ref

Extract repeated structures into components and reference them with $ref. The JSON pointer #/components/schemas/User means "components.schemas.User in this file"; refs may also point at other files, e.g. ./schemas/user.yaml.

YAML

components:
  parameters:
    UserId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
  responses:
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

schema 的常用关键字

Keyword	Meaning	Example
type	Data type	string / integer / object / array
format	Semantic hint	int64 / date-time / email
enum	Fixed value set	[pending, paid, shipped]
required	Mandatory properties	[id, name]
minimum / maximum	Numeric bounds	minimum: 0
pattern	Regex constraint	'^1[3-9]\d{9}$'
oneOf / anyOf / allOf	Composition	See advanced chapter

OpenAPI 3.0 schemas are a subset of JSON Schema; unsupported keywords such as patternProperties are silently ignored by some tools. Use 3.1 for full JSON Schema.

顶层结构

YAML

openapi: 3.0.3            # 规范版本，必填
info:                     # 元信息，必填
  title: User API
  version: 1.0.0
  description: 用户服务接口
servers:                  # 服务器列表
  - url: https://api.example.com/v1
    description: 生产
  - url: http://localhost:8080/v1
    description: 本地
paths:                    # 路径与操作，必填
  /users:
    get: { ... }
    post: { ... }
components:               # 可复用组件
  schemas: { ... }
  parameters: { ... }
  responses: { ... }
  securitySchemes: { ... }

paths 与 operation

paths 的键是路径模板，值是一组 HTTP 方法。每个 operation 至少要有 responses，通常还有 summary、parameters、requestBody、tags。

YAML

paths:
  /users/{id}:
    get:
      tags: [Users]
      summary: 查询单个用户
      operationId: getUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components 与 $ref

把重复出现的结构抽到 components 下，用 $ref 引用。JSON 指针写法 #/components/schemas/User 表示「本文件 components.schemas.User」。引用可以跨文件：./schemas/user.yaml。

YAML

components:
  parameters:
    UserId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
  responses:
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

schema 的常用关键字

关键字	含义	例子
type	数据类型	string / integer / object / array
format	语义提示	int64 / date-time / email
enum	固定取值	[pending, paid, shipped]
required	必填属性	[id, name]
minimum / maximum	数值范围	minimum: 0
pattern	正则约束	'^1[3-9]\d{9}$'
oneOf / anyOf / allOf	组合	见高级章节

OpenAPI 3.0 的 schema 是 JSON Schema 的子集，不支持的写法（如 patternProperties）会被部分工具忽略。要完整 JSON Schema 请用 3.1。

OpenAPI 规范基础

顶层结构

paths 与 operation

components 与 $ref

schema 的常用关键字

顶层结构

paths 与 operation

components 与 $ref

schema 的常用关键字

Friends & Partners