Swagger Edit介绍
Swagger是专门用来管理接口一个工具。在开发过程中,接口一直是纷争的聚焦点,能有效管理接口(保存好记录、及时更新、方便查看、接口测试)。会让整个项目开发效率提升很大。
而其中Swagger Edit是用来编辑接口文档的小程序,简单易用。在官网上分为在线编辑和下载代码线下编辑,两种编辑方式。Swagger是通过YAML来定义你的接口规范。可以通过接口文档帮你生成不同框架的服务端和客户端,方便你mock和契约测试。最后导出JSON格式的API规范,通过Swagger UI对外发布。下图就是Swagger Edit界面:

安装
1.下载并且安装node.js
2. npm install -g http-server
3. 下载项目https://github.com/swagger-api/swagger-editor 并且解压。
4. 进入swagger-editor文件夹。运行http-server命令。
5. 进入http://127.0.0.1 就可以看到swagger页面了。

界面介绍
swagger edit界面分为导航栏和工作区。导航栏是对接口文档的处理用,下面会介绍到。
工作区就是我们花时间最多的地方。分为左右区域,左边是编辑区,右边是显示区。左边编辑区使用的YAML语法来编写,只要一修改右边显示区立刻有变化,使用很便捷。进入swagger edit会默认填入一个demo文档,通常我们只需要修改demo文档,就能制作我们想要的接口文档。如下图:

编写完文档点击展示区的excute,进行测试接口。如下图

ps:Swagger Edit修改会后会立即把数据保存到浏览器Local Storage里面,所以不用担心关闭浏览器就会把数据丢失。只要不清缓存,不重装浏览器,这数据会一直存在。

File
这个用来导出/引入接口文件在swagger edit里面进行编辑,也可以输出YAML/JSON格式。这个如果你是非在线版,编辑一半想下次在编辑,建议先导出备份,避免数据丢失。

convert to YAML
把编辑区转换成YAML格式。

Generate Server
把接口文档生成服务器文件,导出一个压缩包,接口文档生成java、js等服务器文件。很实用工具,让你写少很多代码。

导出spring-boot

导出nodeJS

Generate Client
生成查看接口文档。编写好下一步就是展示。这里可以选择导出什么格式的接口文档。

导出html

文档编写语法
文档是YAML语法来编辑,这里不解说。这里提供各字段的中文解释,大家应该看的懂。对语法不懂,请查看YAML语法 阮一峰

swagger: '2.0' # swagger的版本
info:
title: 文档标题
description: 描述
version: "v1.0" # 版本号
termsOfService: "" # 文档支持截止日期
contact: # 联系人的信息
name: "" # 联系人姓名
url: "" # 联系人URL
email: "" # 联系人邮箱
license: # 授权信息
name: "" # 授权名称,例如Apache 2.0
url: "" # 授权URL
host: api.haofly.net # 域名,可以包含端口,如果不提供host,那么默认为提供yaml文件的host
basePath: / # 前缀,比如/v1
schemes: # 传输协议
- http
- https

securityDefinitions: # 安全设置
api_key:
type: apiKey
name: Authorization # 实际的变量名比如,Authorization
in: header # 认证变量放在哪里,query或者header
OauthSecurity: # oauth2的话有些参数必须写全
type: oauth2
flow: accessCode # 可选值为implicit/password/application/accessCode
authorizationUrl: 'https://oauth.simple.api/authorization'
tokenUrl: 'https://oauth.simple.api/token'
scopes:
admin: Admin scope
user: User scope
media: Media scope
auth:
type: oauth2
description: "" # 描述
authorizationUrl: http://haofly.net/api/oauth/
name: Authorization # 实际的变量名比如,Authorization
tokenUrl:
flow: implicit # oauth2认证的几种形式,implicit/password/application/accessCode
scopes:
write:post: 修改文件
read:post: 读取文章

security: # 全局的安全设置的一个选择吧
auth:
- write:pets
- read:pets

consumes: # 接收的MIME types列表
- application/json # 接收响应的Content-Type
- application/vnd.github.v3+json

produces: # 请求的MIME types列表
- application/vnd.knight.v1+json # 请求头的Accept值
- text/plain; charset=utf-8
tags: # 相当于一个分类
- name: post
description: 关于post的接口

externalDocs:
description: find more info here
url: https://haofly.net

paths: # 定义接口的url的详细信息
/projects/{projectName}: # 接口后缀,可以定义参数
get:
tags: # 所属分类的列表
- post
summary: 接口描述 # 简介
description: # 详细介绍
externalDocs: # 这里也可以加这个
description:
url:
operationId: "" # 操作的唯一ID
consumes: [string] # 可接收的mime type列表
produces: [string] # 可发送的mime type列表
schemes: [string] # 可接收的协议列表
deprecated: false # 该接口是否已经弃用
security: # OAuth2认证用
- auth:
- write:post
- read: read
parameters: # 接口的参数
- name: projectName # 参数名
in: path # 该参数应该在哪个地方,例如path、body、query等,但是需要注意的是如果in body,只能用schema来指向一个定义好的object,而不能直接在这里定义
type: string # 参数类型
allowEmptyValue: boolean # 是否允许为空值
description: 项目名 # 参数描述
required: true # 是否必须
default: * # 设置默认值
maximum: number # number的最大值
exclusiveMaximum: boolean # 是否排除最大的那个值
minimum: number # number的最小值
exclusiveMinimum: boolean
maxLength: integer # int的最大值
minLength: integer
enum: [*] # 枚举值
items: # type为数组的时候可以定义其项目的类型
- $ref: "#/parameters/uuidParam" # 这样可以直接用定义好的
responses: # 设置响应
200: # 通过http状态来描述响应
description: Success # 该响应的描述
schema: # 定义返回数据的结构
$ref: '#/definitions/ProjectDataResponse' # 直接关联至某个model

/another: # 另一个接口
responses:
200:
description:
schema:
type: object
properitis:
data:
$ref: '#/definitions/User' # 关联

definitions: # Model/Response的定义,这里的定义不强制要求返回数据必须和这个一致,但是在swagger-ui上,会展示这里面的字段。
Product: # 定义一个model
type: object # model类型
properties: # 字段列表
product_id: # 字段名
type: integer # 字段类型
description: # 字段描述
product_name:
type: string
description:
ProjectDataResponse:
type: object
properties:
data:
$ref: '#/definitions/ProjectResponse' # model之间的关联,表示在data字段里面包含的是一个ProjectResponse对象
parameters: # 可以供很多接口使用的params
limitParam:
name: limit
in: query
description: max records to return
required: true
type: integer
format: int32
responses: # 可以供很多接口使用的responses
NotFound:
description: Entity not found.

参考
Swagger官网:http://swagger.io/
Swagger Github:https://github.com/swagger-api
Swagger Editor在线demo:http://editor.swagger.io/#/
Swagger UI在线demo:http://petstore.swagger.io/
---------------------
作者:JarunWang
来源:CSDN
原文:https://blog.csdn.net/rth362147773/article/details/78992043
版权声明:本文为博主原创文章,转载请附上博文链接!

Swagger Edit 安装和使用教程的更多相关文章

  1. 【转】真正从零开始,TensorFlow详细安装入门图文教程!(帮你完成那个最难的从0到1)

    AI这个概念好像突然就火起来了,年初大比分战胜李世石的AlphaGo成功的吸引了大量的关注,但其实看看你的手机上的语音助手,相机上的人脸识别,今日头条上帮你自动筛选出来的新闻,还有各大音乐软件的歌曲& ...

  2. NSIS安装制作基础教程[初级篇], 献给对NSIS有兴趣的初学者

    NSIS安装制作基础教程[初级篇], 献给对NSIS有兴趣的初学者 作者: raindy 来源:http://bbs.hanzify.org/index.php?showtopic=30029 时间: ...

  3. 真正从零开始,TensorFlow详细安装入门图文教程!

    本文转载地址:https://www.leiphone.com/news/201606/ORlQ7uK3TIW8xVGF.html AI这个概念好像突然就火起来了,年初大比分战胜李世石的AlphaGo ...

  4. Step by Step 真正从零开始,TensorFlow详细安装入门图文教程!帮你完成那个最难的从0到1

    摘要: Step by Step 真正从零开始,TensorFlow详细安装入门图文教程!帮你完成那个最难的从0到1 安装遇到问题请文末留言. 悦动智能公众号:aibbtcom AI这个概念好像突然就 ...

  5. Swagger Edit自动生成代码工具

    一.swagger简介 swagger是一套开源的API设计工具,包括Swagger UI和Swagger Editor等.其中swagger edit是用来编辑接口文档的小程序,非常简单易用.在官网 ...

  6. 2018年Unity结合Android SDK下载安装及配置教程

    原文:2018年Unity结合Android SDK下载安装及配置教程 首先声明: Unity版本2017.1f3        最近试着在Unity中利用网易做AR开发时,发布项目文件需要发布到An ...

  7. .net core的Swagger接口文档使用教程(二):NSwag

    上一篇介绍了Swashbuckle ,地址:.net core的Swagger接口文档使用教程(一):Swashbuckle 讲的东西还挺多,怎奈微软还推荐了一个NSwag,那就继续写吧! 但是和Sw ...

  8. CentOS7下自定义目录安装mono+jexus教程

    一.阅读前须知: 1.本文属于安装完Centos7之后的步骤 2.如果还不了解mono,请点击mono 3.本篇主要内容是使用自定义目录安装mono+jexus教程,使用默认目录请查看使用默认目录安装 ...

  9. CentOS7下默认目录安装mono+jexus教程

    一.阅读前须知: 1.本文属于安装完Centos7之后的步骤 2.如果还不了解mono,请点击mono 3.本篇主要内容是使用默认目录安装mono+jexus教程,使用自定义目录请查看使用自定义目录安 ...

随机推荐

  1. 「汇编」加深理解段地址*10H(*16)必须是16的倍数

    王爽的汇编语言,有这样一道题: 检测点2.2 (2)  有一数据存放在内存20000H单元中,现给定段地址为SA,若想用偏移地址寻到此单元.则SA应满足的条件是:最小为         , 最大为   ...

  2. UEditor1.2.6.0在.net环境下使用

    UEditor1.2.6.0 1.百度百科词条 2.UEditor官方网站 [CKEditor+CKFinder的配置实用,可查看博主另一篇文章] 第一次接触UEditor还是在2011年的下半年里, ...

  3. winform 仿web 滑块验证

    winform 仿web 滑块验证 效果如下: 源码下载地址: https://download.csdn.net/download/u011392711/11109687

  4. R语言学习——图形初阶之散点图

    使用R内置的数据框mtcars,绘制车身重量与每加仑汽油行驶的英里数的散点图,要求横轴为车身重量(wt),纵轴为每加仑汽油行驶的英里数(mpg),并添加最优拟合曲线.标题,输出为pdf文件.代码实现如 ...

  5. java 开发工具记录

    jenkins 持续构建项目 lombok  优雅代码插件 sonarqube 代码检测插件

  6. 随心测试_软测基础_004<测试人员工作职责>

    接上篇续,依据_软测基础体系:<依据不同的测试对象,选取适合的方法,按照设计的流程完成测试工作,检验整个过程是否达到测试的目的>.“学以致用”,实践于工作职责 常见面试题: —— 诸如以下 ...

  7. git@github.com: Permission denied (publickey).////remote: Permission to xxx/test.git denied to xxx.等权限问题

    Error msg git@github.com: Permission denied (publickey) 或者: remote: Permission to xxx/test.git denie ...

  8. 新增和修改页面的用例设计和Bug提交

    问题: 新增页面和修改页面,基本上输入框都一样,那比如同一个输入框的用例设计: 1. 写了新增页面的用例,修改页面对该输入框还有再写一遍用例的必要吗? 2. 执行用例时,新增页面验证了必填项,长度,数 ...

  9. 一入OI深似海 1 —— 偶然遇见,命运选择

    记得还是三年级(还是四年级?人老了都忘了)吧, 那时候我还是个愣头青, 学校的编程班在每个班强制招人, 我就屁颠屁颠被赶去去上课了. 一开始的课完全听不懂, 导致没过多久我同班的人一个个走了, 我为了 ...

  10. js检查身份证号是否正确

    转的,比较完善的验证身份证号的代码 /* check(ID)验证身份证号码 返回值:0 : "是正确的身份证号" 1 : "身份证校验不符合求和模11=1这个等式&quo ...