赞
踩
拷贝进网站查看
swagger: “2.0” 使用definitions/具体结构
openapi: 3.0.0 使用components/具体结构
也可以有多层目录,例如:components/schema/具体结构、components/securitySchema/具体结构 等。
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: ""
#必要字段!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即为1和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: 别名
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'
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。