swagger使用

1/

         打开swagger在线编辑器http://editor.swagger.io/#/

2/

 

         新建swagger页面

         

3/

       常用字段格式说明：

host： 接口访问地址，包含端口，格式：IP:端口
schemes: 访问方式， http或https
basePath: 根路径
paths：包含文档包含的所有接口列表，具体如下表
文档属性 属性说明
/api/auth/getcaptcha/{mobile}/{sid}/{uuid}: 访问路径
get: Method: get, put, post, delete
summary: 获取手机验证码 接口简介
description: | 　
获取手机验证码。 接口详细描述
parameters: 参数列表开始
- name: mobile 参数名称
in: path 参数类型：query: 以名值对的形式在URL中出现，path:以path方式出现
description: 手机号码 参数描述
required: true 是否必填：true|false
type: string 参数数据类型
format: string 参数格式，参见swagger-editor官方资料
- name: sid 　
in: path 　
description: 用户标识 　
required: true 　
type: string 　
format: string 　
- name: uuid 　
in: path 　
description: 请求唯一标识符 　
required: true 　
type: string 　
format: string 　
tags: 标签，相同TAGS的接口会在页面上归类到一起
- 认证 标签值
responses: 接口响应，可配置不同的响应码对应不同的response, 也可以配置default response
default: 默认响应
description: An Object of RestResult 描述
schema: 响应具体描述
type: array 参见swagger-editor官方资料
items: 　
$ref: '#/definitions/RestResult' 参见swagger-editor官方资料

编辑完成之后修改为   .ymal  结尾的文件

4/

    编写html文件

参考：smsapi.html
修改其中的var url = "/yaml文件名称.yaml";为自己编写的yaml文件名称。

 

5/

    在index.html中加入文档链接

在index.html中增加：
<li><br></li>
<li class="get operation">
<div class="heading">
<a href="/smsapi.html">手机短信API文档</a>
</div>
</li>

 

6/

 

上传至服务器即可打开