open api 规范例子

open api 规范例子

openapi: 3.0.3
info: # api 基本信息描述
  title: open api 规范学习
  description: 详细说明
  version: 0.0.1 版本号
  contact:
    name: 作者名称,能直接关联邮件地址
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers: # 这是一个数组，提供服务器的连接信息。如果没有提供 servers 属性或者是一个空数组，那么默认为是url值为 /
  - url: 'http://example.com/' # 直接指定一个地址
    description: 指定服务器地址 # 描述
  - url: '{http}{domain}:{port}' # 可通过参数控制的地址
    description: 自定义服务器地址
    variables: #一组变量和值的映射，这些值被用来替换服务器URL地 址内的模板参数。
      http: # 声明参数名称
        enum: # 枚举类型
          - 'http://' # 自定参数1
          - 'https://' # 自定参数2
          - ''
        default: http:// # 必选.默认值
        description: http 方式 #参数名称说明
      domain:
        default: example.com # 默认是输入框模式
        description: 可输入自定域名或IP地址
      port:
        default: '80'
        description: 可输入自定端口
paths: # 路径地址列表对象
  /: # 路径名
    description: 首页地址 # 可选描述字段
    get: # 请求模式
      responses: # 返回参数对象
        200: # 定义成功返回例子
          description: 返回成功的描述
          content:
            text/html: # 返回内容格式
              schema:
                type: string # 值类型
                default: 你好
      parameters: # 请求下参数配置对象
        - name: page # get 参数名称
          in: query # get 模式
          description: get值page参数 # 参数描述
          required: false # 是否必填状态
          schema:
            type: string # 值对象类型
            default: 1 # 默认值
          allowEmptyValue: true # 是否允许为空
  /login:
    description: 路径的描述字段
    summary: 描述包含的操作  #可选,描述包含的操作
    post:
      description: '登录请求'
      responses: # 返回信息说明
        200:
          description: 返回成功的描述
          content:
            application/json:
              schema:
                type: string
      security: # 指定该请求下单独的凭证对象
        - headerKey: []
      parameters:
        - name: page # 添加 get 参数
          in: query
          description: page 参数
          required: false
          schema:
            type: integer
            format: int32
            default: 1
      requestBody: # post 请求参数内容对象
        content:
          application/x-www-form-urlencoded: # 参数编码类型
            schema:
              type: object # 格式
              properties:
                name: # 定义参数对象
                  description: '用户名参数'
                  type: string
                  default: 'test'
                password:
                  description: '密码参数'
                  type: string
                  default: '1234'
                  format: password
components: # 组件
  securitySchemes: # 必选，可用秘密凭证列表
    headerKey: # 声明自定义凭证对象
      type: apiKey # 凭证类型 自定义键与值的模式
      name: token # http header 标头键名
      in: header # 插入位置
      description: token 描述 # 凭证的描述
    tokenJWT:
      type: http # http 标准认证模式
      scheme: bearer # 凭证模式
      bearerFormat: JWT # 格式
      description: token 描述 2
security: # 所有接口可调用的秘密凭证列表
  - tokenJWT: [] # 对应组件内的数组名称

参考资料：

OpenAPI-Specification/3.0.0.zhCN.md at master · fishead/OpenAPI-Specification (github.com)

OpenAPI Specification v3.1.0 | Introduction, Definitions, & More