# Swagger

# 参考文档

Swagger 官网 (opens new window)

# 是什么

一种接口文档定义规范。
帮助开发人员设计、构建、记录和使用 RESTful Web 服务。
工具集支持自动文档、代码生成和测试用例生成。

# 基本格式

同时支持 yaml、json 的写法，推荐使用 yaml。
文档结构
- info：文档描述信息。
- host：接口域名。
- basePath：接口基础路径。
  - 一般为接口版本号。
  - 如果接口没有独立域名，也可以是自定义的一个路径，如 api。
- tags：接口标签，用于接口分类，可以简单描述一类接口的用途，增强文档可读性。
- schemes：传输协议，一般为 http、https，群脉只支持 https。
- consumes：请求数据类型，群脉只支持 application/json。
- produces：返回数据类型，群脉只支持 application/json。
- securityDefinitions：权限认证方式定义，群脉采用 api_key 的方式，在 http header 中设置 x-access-token。
- paths：接口定义，采用 RESTful 风格。
- definitions：对象定义。

# Swagger Editor

基础信息
- swagger：swagger版本
- info:
  - title：标题
  - description：文档说明
  - version：文档版本
基本 url
- host：主机地址
- basePath：url 前缀
- schemes：网络请求协议：http/https
API 标签
- tags：
接口定义
- paths：
  - /user：
    - post：新增接口
      - tags：所属标签
      - operationId:方法名(生成代码后即是controller层的接口方法名)
      - produces：生产格式：json/xml
      - consumes：消费格式：json/xml
      - parameters：请求参数定义
        -name：参数名
        
        in：参数类型：可选：body/query/path，分别代表：请求体 /url 拼接参数 /url 占位符替换
        
        required：是否必需：true/false
        
        schema：参数结构,可引用 definitions 中定义的数据模型
        $ref:'#/definitions/User'
        
        responses：返回格式定义
    - get：查询接口
    - delete：删除接口
    - put：修改接口
  - '/user/{userId}':
    - get：查询详情接口
数据模型定义
- definitions:
  - User：用户 User 类
    - type：类型:object
    - properties：参数列表
      - userId：用户 ID
        type：参数类型:object/integer/string/array等
        
        format：参数格式：int32/date-time
        
        items：若是前序的 type 为 array，则需要定义 items 中的数据类型
        
        type：
        
        description：参数描述

# 讨论区

由于评论过多会影响页面最下方的导航，故将评论区做默认折叠处理。

点击查看评论区内容，渴望您的宝贵建议~

← Swagger 目录