创建环境
使用docker创建环境简单快速,详情参考
docker run -d -p 8100:8080 swaggerapi/swagger-editor
然后打开浏览器输入0.0.0.0:8100进入swagger editor开始编辑
编辑
按照restful规范编辑接口
参考文档
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
效果图
编辑完成可以导出json或yaml类型,或者直接导出服务
也可以导出json格式的文件，然后运行docker run -d -p 9999:8080 -e SWAGGER_JSON=/foo/swagger.json -v /home/w/pyproject/fs-business:/foo swaggerapi/swagger-ui-v挂载的是你刚才导出的就是json文件，这样别人就可以通过访问文档(你的)IP:9999
