示例

拷贝进网站查看
swagger: “2.0” 使用definitions/具体结构
openapi: 3.0.0 使用components/具体结构
也可以有多层目录，例如：components/schema/具体结构、components/securitySchema/具体结构 等。

示例1

swagger: "2.0"
schemes:
  - https
info: 
  description: "kramer's send message"
  version: "v34"
  title: "kramer"
host: "open.feishu.cn"

paths:
  /open-apis/im/v1/messages:
    post:
      tags:
      # tags send_message是说以下内容在send_message命名空间下
        - "send_message"
      # description 接口描述
      description: "发送消息"
      # 功能相当于description，两者显示位置不同
      summary: "send a message"
      # 输入格式，是个数组
      consumes:
        - "application/json"
      # 输出格式，是个数组
      produces:
        - "application/json"
      # operationId接口操作标识（必填）
      operationId: "SendMessages"
      # parameters参数信息
      parameters:
        # name 参数名
        - name: "Authorization"
          description: "tenant_access_token"
          # required 是否必填
          required: true
          # in 参数位置；body, header, formData, query, path（body只能有一个）
          in: "query"
          # type 参数类型
          type: "string"
        - name: "receive_id_type"
          description: "消息接收者id类型"
          required: true
          in: "query"
          # enum 枚举可选值
          enum:
            - "open_id"
            - "user_id"
            - "union_id"
            - "email"
            - "chat_id"
          type: "string"
        - name: "request_body"
          description: "请求体"
          required: true
          in: "body"
          # schema 参数引用架构
          schema: 
            # $ref 引用
            $ref: "#/definitions/send_message"
      # responses 响应体
      responses:
        # 200 状态码
        200:
          description: "success"
          schema: 
            $ref: "#/definitions/send_message_response"
# definitions shcmea引用结构的定义
definitions:
  # 定义名为send_message的schema
  send_message:
    # schema的type类型
    type: "object"
    # schema的成员参数properties
    properties:
      receive_id:
        type: "string"
        description: "依据receive_id_type的值，填写对应的消息接收者id"
      content:
        type: "string"
        description: "消息内容，json结构，不同msg_type对应不同内容"
      msg_type:
        type: "string"
        description: "消息类型"
    # required 统一定义哪些参数是必填
    required:
      - "receive_id"
      - "content"
      - "msg_type"
  send_message_response:
    type: "object"
    properties:
      code: 
        type: "string"
        description: "错误码，非 0 表示失败"
      msg:
        type: "string"
        description: "错误描述"
      data:
        type: "object"
        properties:
          message_id:
            type: "string"
            description: ""
          root_id:
            type: "string"
            description: ""

示例2

#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: '2.0'
#必要字段！描述API接口信息的元数据
info:
  #接口标题
  title: swagger说明文档　
  #接口文档的描述
  description: 学习Swagger
  #版本号
  version: 1.0.0
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．
host: 127.0.0.1
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
basePath: /api
#指定调用接口的协议，必须是:"http", "https", "ws", "wss"．默认是http.-表示是个数组元素，即schemes接受一个数组参数
schemes:
  - http
  - https
#对应与http协议头request的Accept，调用者可接受类型,默认是*/*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性
produces:
  - application/json
#必要字段!定义可有可操作的API
paths:
  /users:
   #必要字段!定义HTTP操作方法，必须是http协议定义的方法
    get:
      #接口概要
      summary: 查询所有用户信息
      #接口描述
      description: 查询出所有用户的所有信息，用户名，别名
      #标签，方便快速过滤出User相关的接口
      tags:
        - User
      #返回值描述，必要自动
      responses:
        #返回的http状态码
        200:
          description: 所有用户信息或者用户的集合信息
          #描述返回值
          schema:
            #返回值格式，可选的有array,integer,string,boolean
            type: array
            #针对array,每个条目的格式,type定义为array．必要填写items
            items:
              #引用在definitions下定义的Users
              $ref: '#/definitions/User'
        #执行出错的处理
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
            #值类型
            type: object
            #定义属性
            properties:
            #属性名
              message:
                #类型
                type: string
    #即对于同一个url定义两个不同的方法，表示两个接口
    post:
      description: 注册一个用户
      #请求参数
      parameters:
          #参数key
        - name: username
          #传递方法，formData表示表单传输，还有query表示url拼接传输，path表示作为url的一部分
          #body表示http头承载参数(body只能有一个,有body不能在有其他的)
          in: formData
          #参数描述
          description: 用户名，不能使用已经被注册过的
          #参数是否必要，默认false
          required: true
          #参数类型，可选的包括array,integer,boolean,string.使用array必须使用items
          type: string
        - name: password
          in: formData
          description: 用户登陆密码，加密传输，加密存储
          required: true
          type: string
        - name: alias
          in: formData
          type: string
          description: 用户别名
          #非必要字段
          required: false
      responses:
        #返回的http状态码
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
             #值类型
              type: object
              #定义属性
              properties:
              #属性名
                status:
                  #类型
                  type: boolean
                  #描述
                  description: 是否成功
        #执行出错的处理
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
            #值类型
            type: object
            #定义属性
            properties:
            #属性名
              message:
                #类型
                type: string
  /users/{
    id}:
    #{id}表示id为请求参数，例如/users/1,/users/2都是对该API的请求，此时id即为１和2
    get:
      summary: 根据用户名id查询该用户的所有信息
      description: 查询出某个用户的所有信息，用户名，别名等
      tags:
        - User
      parameters:
        #上面接口中定义了{id}，则参数列表中必须包含参数id,并且请求类型为path
        - name: id
          in: path
          description: 要查询的用户的用户名,它是唯一标识
          required: true
          type: string
      responses:
        200:
          description: 所有用户信息或者用户的集合信息
          schema:
              $ref: '#/definitions/User'
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              #值类型
              type: object
              #定义属性
              properties:
              #属性名
                message:
                  #类型
                  type: string
    #http定义的delete方法,删除一个资源
    delete:
      summary: 删除用户
      description: 删除某个用户的信息，被删除的用户将无法登陆
      parameters:
        - name: id
          in: path
          type: string
          required: true
          description: 用户的唯一标示符
      tags:
        - User
      responses:
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
             #值类型
              type: object
              #定义属性
              properties:
              #属性名
                status:
                  #类型
                  type: boolean
                  #描述
                  description: 是否成功
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              #值类型
              type: object
              #定义属性
              properties:
              #属性名
                message:
                  #类型
                  type: string
                  #描述错误信息
    #http定义的patch方法，表示修改一个资源
    patch:
      summary: 用户信息修改
      description: 修改用户信息(用户名别名)
      parameters: 
        - name: id
          in: path
          description: 用户名,要修改的数据的唯一标识符
          required: true
          type: string
        - name: alias
          in: formData
          description: 新的用户别名
          required: true
          type: string
      tags:
        - User
      responses:
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
            #值类型
              type: object
              #定义属性
              properties:
              #属性名
                status:
                  #类型
                  type: boolean
                  #描述
                  description: 是否成功
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              #值类型
              type: object
              #定义属性
              properties:
              #属性名
                message:
                  #类型
                  type: string
                  #描述错误信息
definitions:
  User:
    #值类型
    type: object
    #定义属性
    properties:
    #属性名
      id:
        #类型
        type: string
        #描述
        description: 用户的唯一id
      username:
        type: string
        description: 用户名
      alias:
        type: string
        description: 别名

示例3 openapi 3.0.0

openapi: 3.0.0
info:
  version: 1.2.0
  title: ka config request
  description: 企培配置API
servers:
  - url: 'http://localhost:18080/api/v1/config'

components:
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    errorResponse:
      type: object
      properties:
        code:
          type: string
          description: 状态码
        message:
          type: string
          description: 描述信息
    Error:
      type: object
      properties:
        timestamp:
          type: string
        status:
          type: integer
          format: int32
        error:
          type: string
        path:
          type: string
    defaultConfig:
      type: object
      required:
        - welcome_message
        - calendar_permissions
        - b_show_on_main_calendar
        - event_reminder_minutes
        - task_complete_statistics
      properties:
        sync_method:
          type: string
          description: 同步方法, 可选字段, enum(lark_cloud_table,interface, third_party_product), 可以传枚举索引(int)或者值(string)
        sync_frequency:
          type: string
          description: 同步频率, 可选字段, enum(real_time, cron), 可以传枚举索引(int)或者值(string)
        welcome_message:
          type: string
          description: 入群欢迎语, 最长2047字符
        calendar_permissions:
          type: string
          description: 日历公开范围, enum(private, public, show_only_free_busy), 可以传枚举索引(int)或者值(string)
        b_show_on_main_calendar:
          type: boolean
          description: 是否展示到用户主日历
        event_reminder_minutes:
          description: (摘自飞书开放平台文档) 日程提醒时间的偏移量，正数时表示在日程开始前X分钟提醒，负数时表示在日程开始后X分钟提醒 取值范围：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        task_complete_statistics:
          type: string
          description: 群内任务提醒, enum(enable, disable, only_teacher_and_organizer), 可以传枚举索引(int)或者值(string)
        task_reminder_minutes:
          description: (摘自飞书开放平台文档) 相对于截止时间的提醒时间（如提前 30 分钟，截止时间后 30 分钟，则为 -30）
          type: array
          items:
            type: integer
            format: int32
        can_join_course_via_calendar:
          type: boolean
          description: 是否可以通过日程加入课程
        auto_create_chat:
          type: boolean
          description: 是否自动创建课程群聊
        advance_days:
          type: integer
          format: int32
          description: 自动创建群聊的提前时间（单位：天）
        welcome_type:
          type: string
          description: 欢迎语格式
        title:
          type: string
          description: 欢迎语标题
        text:
          type: string
          description: 欢迎语正文内容
        button_text:
          type: string
          description: 按钮文本
        button_url:
          type: string
          description: 按钮链接
        img_key:
          type: string
          description: 图片
        task_id:
          type: integer
          format: int64
          description: 任务id
        chat_reminder_days:
          type: string
          description: 群聊
        reminder_content:
          type: string
          description: 保留文本
    course:
      type: object
      required:
        - course_id
        - name
        - description
        - calendar_permissions
        - b_show_on_main_calendar
        - manager
      properties:
        course_id:
          type: string
          description: 课程 id
        name:
          type: string
          description: 课程名称
        description:
          type: string
          description: 课程描述
        calendar_permissions:
          type: string
          description: 日历公开范围, enum(private, public, show_only_free_busy), 可以传枚举索引(int)或者值(string)
        b_show_on_main_calendar:
          type: boolean
          description: 是否展示到用户主日历
        manager:
          type: array
          description: 课程管理员列表
          items:
            type: object
            properties:
              name:
                type: string
    courseConfig:
      type: object
      required:
        - welcome_message
        - calendar_permissions
        - b_show_on_main_calendar
      properties:
        welcome_message:
          type: string
          description: 入群欢迎语, 最长2047字符
        calendar_permissions:
          type: string
          description: 日历公开范围, enum(private, public, show_only_free_busy), 可以传枚举索引(int)或者值(string)
        b_show_on_main_calendar:
          type: boolean
          description: 是否展示到用户主日历
        event_reminder_minutes:
          description: (摘自飞书开放平台文档) 日程提醒时间的偏移量，正数时表示在日程开始前X分钟提醒，负数时表示在日程开始后X分钟提醒 取值范围：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        can_join_course_via_calendar:
          type: boolean
          description: 是否可以通过日程加入课程
        auto_create_chat:
          type: boolean
          description: 是否自动创建群聊
        advance_days:
          type: integer
          format: int32
          description: 自动创建群聊提前时间（单位：天）
        need_survey:
          type: boolean
          description: 是否需要问卷
        survey_url:
          type: string
          description: 问卷链接
        welcome_type:
          type: string
          description: 欢迎语类型
        title:
          type: string
          description: 欢迎语标题
        text:
          type: string
          description: 欢迎语正文内容
        button_text:
          type: string
          description: 按钮文本
        button_url:
          type: string
          description: 按钮链接
        img_key:
          type: string
          description: 图片
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/task'

    courseUpdateConfig:
      type: object
      required:
        - calendar_permissions
        - b_show_on_main_calendar
      properties:
        calendar_permissions:
          type: string
          description: 日历公开范围, enum(private, public, show_only_free_busy), 可以传枚举索引(int)或者值(string)
        b_show_on_main_calendar:
          type: boolean
          description: 是否展示到用户主日历
        event_reminder_minutes:
          description: (摘自飞书开放平台文档) 日程提醒时间的偏移量，正数时表示在日程开始前X分钟提醒，负数时表示在日程开始后X分钟提醒 取值范围：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        tasks:
          description: 任务列表
          type: array
          items:
            type: object
            required:
              - task_id
              - task_complete_statistics
            properties:
              task_id:
                type: integer
                format: int64
                description: 任务id
              task_complete_statistics:
                type: string
                description: 群内任务提醒, enum(enable, disable, only_teacher_and_organizer), 可以传枚举索引(int)或者值(string)
              task_reminder_minutes:
                description: (摘自飞书开放平台文档) 相对于截止时间的提醒时间（如提前 30 分钟，截止时间后 30 分钟，则为 -30）
                type: array
                items:
                  type: integer
                  format: int32
    task:
      type: object
      required:
        - task_id
        - name
        - description
        - task_complete_statistics
      properties:
        task_id:
          type: string
          description: 任务 id
        name:
          type: string
          description: 任务名称
        description:
          type: string
          description: 任务描述
        task_complete_statistics:
          type: string
          description: 群内任务提醒, enum(enable, disable, only_teacher_and_organizer), 可以传枚举索引(int)或者值(string)
        task_reminder_minutes:
          description: (摘自飞书开放平台文档) 相对于截止时间的提醒时间（如提前 30 分钟，截止时间后 30 分钟，则为 -30）
          type: array
          items:
            type: integer
            format: int32
    taskConfig:
      type: object
      required:
        - task_complete_statistics
      properties:
        task_complete_statistics:
          type: string
          description: 群内任务提醒, enum(enable, disable, only_teacher_and_organizer), 可以传枚举索引(int)或者值(string)
        task_reminder_minutes:
          description: (摘自飞书开放平台文档) 相对于截止时间的提醒时间（如提前 30 分钟，截止时间后 30 分钟，则为 -30）
          type: array
          items:
            type: integer
            format: int32
    pageInfo:
      type: object
      required:
        - page_size
        - page_num
        - total_cnt
      properties:
        page_size:
          type: integer
          format: int32
          description: 页面大小
        page_num:
          description: 页码（从0开始)
          type: integer
          format: int32
        total_cnt:
          description: 数据总数
          type: integer
          format: int32
    courseListConfig:
      type: object
      required:
        - welcome_message
        - calendar_permissions
        - b_show_on_main_calendar
        - event_reminder_minutes
        - task_complete_statistics
      properties:
        welcome_message:
          type: string
          description: 入群欢迎语, 最长2047字符
        calendar_permissions:
          type: string
          description: 日历公开范围, enum(private, public, show_only_free_busy), 可以传枚举索引(int)或者值(string)
        b_show_on_main_calendar:
          type: boolean
          description: 是否展示到用户主日历
        event_reminder_minutes:
          description: (摘自飞书开放平台文档) 日程提醒时间的偏移量，正数时表示在日程开始前X分钟提醒，负数时表示在日程开始后X分钟提醒 取值范围：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        task_complete_statistics:
          type: string
          description: 群内任务提醒, enum(enable, disable, only_teacher_and_organizer), 可以传枚举索引(int)或者值(string)
        task_reminder_minutes:
          description: (摘自飞书开放平台文档) 相对于截止时间的提醒时间（如提前 30 分钟，截止时间后 30 分钟，则为 -30）
          type: array
          items:
            type: integer
            format: int32



paths:
  /courseconfig:
    put:
      summary: '批量修改课程配置'
      security:
        - tokenAuth: [ ]
      tags:
        - course
      requestBody:
        content:
          application/json:
            schema:
              properties:
                course_config:
                  $ref: '#/components/schemas/courseListConfig'
                course_id_list:
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: 'update success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 状态码
                  message:
                    type: string
                    description: 描述信息
                  data:
                    $ref: '#/components/schemas/courseListConfig'
        'x-40410':
          description: 'course not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /globalcalendar:
    put:
      summary: 开启/关闭全局日历
      tags:
        - default
      security:
        - tokenAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              properties:
                open_global_calendar:
                  type: boolean
      responses:
        '200':
          description: 'update success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 状态码
                  message:
                    type: string
                    description: 描述信息
                  data:
                    properties:
                      open_global_calendar:
                        type: boolean
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /defaultconfig:
    post:
      summary: 更新企业默认配置
      tags:
        - default
      security:
        - tokenAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/defaultConfig'
      responses:
        '200':
          description: 'Created'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 状态码
                  message:
                    type: string
                    description: 描述信息
                  data:
                    $ref: '#/components/schemas/defaultConfig'
        'x-50011':
          description: unexpected response of lark request 'create calendar'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: 获取企业默认配置
      tags:
        - default
      security:
        - tokenAuth: [ ]
      responses:
        '200':
          description: 'require success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 状态码
                  message:
                    type: string
                    description: 描述信息
                  data:
                    $ref: '#/components/schemas/defaultConfig'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /courseconfig/{
    course_id}:
    get:
      summary: '获取某一课程配置'
      security:
        - tokenAuth: [ ]
      tags:
        - course
      parameters:
        - name: course_id
          in: path
          required: true
          description: 课程 id
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/courseConfig'
      responses:
        '200':
          description: 'require success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 状态码
                  message:
                    type: string
                    description: 描述信息
                  data:
                    $ref: '#/components/schemas/courseConfig'
        'x-40410':
          description: 'course not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: '修改某一课程配置'
      security:
        - tokenAuth: [ ]
      tags:
        - course
      parameters:
        - name: course_id
          in: path
          required: true
          description: 课程 id
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/courseUpdateConfig'
      responses:
        '200':
          description: 'update success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: 状态码
                  message:
                    type: string
                    description: 描述信息
                  data:
                    $ref: '#/components/schemas/courseUpdateConfig'
        'x-40410':
          description: 'course not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        'x-40411':
          description: 'task not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'