swagger editor使用

1.访问路径;Swagger Editor

2.导入协议文件

3.填写参数发送请求

官方说明地址：OpenAPI Specification - Version 3.0.3 | Swagger

总结说明： @SWG\Parameter()为请求的参数，需要注意一下格式；@SWG\Response()为响应的参数，最后请求的时候是列表还是一个参数，请求的格式和get的列表和参数的格式是一样的；

3》需要执行命令 ：

以下命令可以直接生成一个seagger.json文档并把文档当到指定位置

swagger文档配置位置 swagger文档的位置 -o 要把生成的文档写入的文件位置（例如 /home/wwwroot/api_doc/swagger-php/bin/swagger /home/wwwroot/test/application/index/controller -o /home/wwroot/api_doc/test.json）

最后访问文档

或者也可以用以下命令直接生成文档swagger-php/bin/swagger生成 swagger.json,

4》参数描述 (@SWGParameter) 常用字段:

name - string

参数名. 通过路径传参(in 取值 “path”)时有注意事项,没用到,懒得看了…

in - string

参数从何处来. 必填. 取值仅限: “query”, “header”, “path”, “formData”, “body”

description - string

参数描述. 最好别太长

type - string

参数类型. 取值仅限: “string”, “number”, “integer”, “boolean”, “array”, “file”

required - boolean

参数是否必须. 通过路径传参(in 取值 “path”)时必须为 true；in取值为formData时可为true可为false；

default - *

默认值. 在你打算把参数通过 path 传递时规矩挺多,我没用到.用到的可以自己看下文档

语法规则

1.固定字段

字段名	类型	描述
swagger	string	必需的。使用指定的规范版本
info	info Object	必需的。提供元数据API
host	string	主机名或ip服务API
basePath	string	API的基本路径
schemes	[string]	API的传输协议。 值必须从列表中:"http","https","ws","wss"。
consumes	[string]	一个MIME类型的api可以使用列表。值必须是所描述的Mime类型
produces	[string]	MIME类型的api可以产生的列表。 值必须是所描述的Mime类型
paths	路径对象	必需的。可用的路径和操作的API
definitions	定义对象	一个对象数据类型生产和使用操作
parameters	参数定义对象	一个对象来保存参数,可以使用在操作。 这个属性不为所有操作定义全局参数。
responses	反应定义对象	一个对象响应,可以跨操作使用。 这个属性不为所有操作定义全球响应
externalDocs	外部文档对象	额外的外部文档
summary	string	什么操作的一个简短的总结。 最大swagger-ui可读性,这一领域应小于120个字符
description	string	解释操作的行为
operationId	string	独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。 工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定
deprecated	boolean	声明该操作被弃用。 使用声明的操作应该没有。 默认值是false

2.字段类型与格式定义

普通名字	type	format	说明
integer	integer	int32	签署了32位
long	integer	int64	签署了64位
float	number	float
double	number	double
string	string
byte	string	byte	base64编码的字符
binary	stirng	binary	任何的八位字节序列
boolean	boolean
date	string	date	所定义的full-date- - - - - -RFC3339
datetime	string	date-time	所定义的date-time- - - - - -RFC3339
password	stirng	password	用来提示用户界面输入需要模糊

模板实例：

swagger: '2.0'
info:
  title: ''
  description: ''
  version: 1.0.0
  termsOfService: ''
  contact:
    email: test@email.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: '0.0.0.0:8000'  #接口的root路径
basePath: /api/v1
tags:
  - name: 文件夹相关操作 #接口分组
    description: 文件夹的相关操作  #分组介绍
schemes:
  - https
  - http
  - ws
  - wss
paths:
  /folders:
      get:
        tags:  #这个是给接口分组,按照上面写的tags
          - 文件夹相关操作
        summary: 获取根目录的同级文件夹目录    #接口功能简介
        description: ''  #接口功能详细介绍
            
        responses:
          200:
            description: OK
            schema:  #结构体信息返回
              $ref: '#/definitions/Folder'  #引用
  /folders/{folderId}:
    get:
      tags: 
        - 文件夹相关操作
      summary: 获取指定目录下的同级目录 
      parameters:
        - in: path  #路由中带{}的要用path，如果需要带参数这里要把path改为query其他的照旧就行
          name: folderId  #名字要和{}中的一致
          required: true
          type: integer  #直接用type这是直接在表示{}中的类型
          format: int64
      responses:  # 返回参数
        200:
          description: OK
          schema:
              $ref: '#/definitions/Folder'
    put:
      tags: 
          - 文件夹相关操作
      summary: 修改文件夹信息
      description: ''
      parameters:  #因为{}中的参数和结构体中的参数都要使用所以要定义两个
          - in: path
            name: folderId
            required: true
            type: integer
            format: int64
          - in: body # 使用json传参使用body，下面就要跟schema，如果要添加参数则为注释内容
            name: body
            required: true
            schema:
              $ref: '#/definitions/Folder'
            schema: 
            	properties:
            		xxx:
            			type: 
      responses:
        200:
          description: OK
          
    post:
      tags: 
      - 文件夹相关操作
      summary: 向该文件夹下创建文件夹
      description: ''
      consumes: # 指定post的请求类型是formdata类型
        - multipart/form-data
      produces:
        - application/json
      parameters:
          - in: path
            name: folderId
            required: true
            type: integer
            format: int64
          - in: formData  # formDatapost的请求类型
            name: folderId
            required: true
            schema: 
              $ref: '#/definitions/Folder'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Folder'
    delete:
      tags: 
        - 文件夹相关操作
        
      summary: 删除文件夹
      
      description: ''
      parameters:
        - in: path
          name: folderId
          required: true
          type: string
          format: string
          description: 文件夹的id用','号隔开
      responses:
        200:
          description: OK
    
    
securityDefinitions:
  petstore_auth:
    type: oauth2
    authorizationUrl: 'http://petstore.swagger.io/oauth/dialog'
    flow: implicit
    scopes:
      'write:pets': modify pets in your account
      'read:pets': read your pets
  api_key:
    type: apiKey
    name: api_key
    in: header
    
definitions:    #公共引用
  Folder:
    type: "object"
    readOnly: true
    required: 
      - folder
    properties:
      folderId:
        description: 输入为父文件夹的id,输出为创建成功的文件夹id
        type: integer
      name:
        description: 文件夹名字
        type: string
      createrTime:
        description: 文件夹上次打开时间
        type: string
      desc:
        description: 文件夹备注
        type: string
      type:
        description: 类型
        type: string
 

              ------------------------------使用过程中可能遇到的错误--------------------------------

1、如果curl中出现这个错误：curl -X GET “https://www.aa.com” -H “accept: 
  application/json” -H “x-access-sign: 11111111” -H “x-access-time: 2019”
 -d “uid: 5”，说明你的请求方式有问题，-d指的是post请求，而你上面用的是get请求，
 关于请求方式如何修改，可以修改文档中的参数，其中有一个“in”的参数代表的是get还
 是post的请求，如果是get请求应改成 in=“path”,如果是post请求，
 应改成in=“formData”！！！
2、
Semantic error at paths./cameralist.get.responses.200.schema.$ref
$refs must reference a valid location in the document
//定义的内容
需在definitions关键字之下进行定义
3、
in 表示处在什么位置 path就是在url后添加 query表示在head中携带 body就是在请求体
定义
4、
 get方法中的 operationId: "devdiskinfoget"跟之前post相同导致get方法错误。
 5、
 dns:
        type: "array"
        description: 
        items:
            type: "string"
报错：Structural error at definitions.NetCardInfoCfg.properties.dns.description
      should be string 
      因为description：没有定义内容 更正description： " "
5、should only have path names that start with `/`
  在某个url路径中缺少 "/"

 也可以去官网社区查询提问：

Swagger Open Source Tools Questions - SmartBear Community