swagger系列二：swagger 语法

flyer_dev 发布于2019-06-28 18:38 / 1229人阅读

摘要：在的下有示例写法。拿过来分析记录。官方注解文档标题部分接口文档测试文档项目效果图接口所支持的协议可以填多种协议主机名或。提供的基本路径，它是相对于。必须以一个前导斜杠开始是拼接出来的。描述跳转链接联系开发者，发送邮件。

在swagger-php的Example下有示例写法。拿过来分析记录。

swagger官方注解：https://bfanger.nl/swagger-explained/#schemaObject go

1. 文档标题部分

/**
 * @SWGSwagger(
 *     schemes={"http"},
 *     host="api.com",
 *     basePath="/v1",
 *     @SWGInfo(
 *         version="1.0.0",
 *         title="API接口文档",
 *         description="测试swagger文档项目",
 *         @SWGContact(
 *             name="wxp",
 *             email="panxxxx@163.com"
 *         )
 *     ),
 *      @SWGExternalDocumentation(
 *         description="wxp",
 *         url="./"
 *     )
 * )
 */

效果图：

schemes: 接口所支持的协议 (可以填多种协议)

host：主机名或ip。

basePath：提供API的基本路径，它是相对于host。必须以一个前导斜杠（/）开始. Base URL 是 host + basePath 拼接出来的。

Info : 文档描述。

version ：版本号。

title :标题。

description : 描述信息。

ExternalDocumentation":外部文档链接。

description:描述

url :跳转链接

Contact ：联系开发者，发送邮件。

name : 开发者姓名

email :邮件地址。

2. tag标签部分，用于文档分类

/**
 * @SWGTag(
 *   name="pet",
 *   description="你的宠物信息",
 *   @SWGExternalDocumentation(
 *     description="查看更多",
 *     url=""
 *   )
 * )
 * @SWGTag(
 *   name="store",
 *   description="查看宠物店订单"
 * )
 * @SWGTag(
 *   name="user",
 *   description="用户操作记录",
 *   @SWGExternalDocumentation(
 *     description="关于宠物店",
 *     url="http://swagger.io"
 *   )
 * )
 */

name : 名称(功能模块)

description : 描述

3. 接口注释写法

    /**
     * @SWGGet(
     *     path="/pet/{petId}",
     *     summary="通过ID查询宠物",
     *     description="返回宠物信息",
     *     operationId="getPetById",
     *     tags={"pet"},
     *     consumes={"application/json", "application/xml"},
     *     produces={"application/xml", "application/json"},
     *     @SWGParameter(
     *         description="ID of pet to return",
     *         in="path",
     *         name="petId",
     *         required=true,
     *         type="integer",
     *         format="int64"
     *     ),
     *     @SWGResponse(
     *         response=200,
     *         description="successful operation",
     *         @SWGSchema(ref="#/definitions/Pet")
     *     ),
     *     @SWGResponse(
     *         response="400",
     *         description="Invalid ID supplied"
     *     ),
     *     @SWGResponse(
     *         response="404",
     *         description="Pet not found"
     *     ),
     *     security={
     *       {"api_key": {}}
     *     }
     * )
     */

Get：请求的 HTTP 方法，支持GET/POST/PUT/DELETE 等 HTTP 标准请求方法

path：请求的路径

summary：接口简介，不能超过120个字符

tags：接口标签，可以是多个

description：接口描述，支持 Markdown 语法

operationId：操作的 ID，全局唯一的接口标识

consumes：接口接收的MIME类型，如 application/json

produces：接口返回的MIME类型,如 application/json

parameters：参数列表

description：参数描述

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

name：参数名.

required：参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.

type=参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"

format：参数格式，如"int64"

response: 描叙了来自API操作的单个响应

response:返回码

description=描述

@SWGSchema(ref="#/definitions/Pet")：引用definitions/Pet定义的对象

4. 定义对象 5.type 为array的写法

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/28495.html

JavaScript 中基于 swagger-decorator 的自动实体类构建与 Swagger

摘要：中基于的自动实体类构建与接口文档生成是笔者对于开源项目的描述，对于不反感使用注解的项目中利用添加合适的实体类或者接口类注解，从而实现支持嵌套地实体类校验与生成等模型生成基于的接口文档生成等等功能。 JavaScript 中基于 swagger-decorator 的自动实体类构建与 Swagger 接口文档生成是笔者对于开源项目 swagger-decorator 的描述，对于不反感使...

Gemini 2019-08-20 18:06 评论0 收藏0
【效率专精系列】善用API统一描述语言提升RestAPI开发效率

摘要：其标准为前身是，提供强大的在线编辑功能，包括语法高亮错误提示自动完成实时预览，并且支持用户以格式撰写导入导出转换文档。团队内部RestAPI开发采用设计驱动开发的模式，即使用API设计文档解耦前端和后端的开发过程，双方只在联调与测试时耦合。在实际开发和与前端合作的过程中，受限于众多因素的影响，开发效率还有进一步提高的空间。本文的目的是优化工具链支持，减少一部分重复和枯燥的劳动。现状...

tianyu 2019-08-16 10:42 评论0 收藏0
api 接口管理工具

摘要：接口管理工具大致分为线上工具和自建工具。安装其他工具上面讲的，不管是线上工具还是自建工具，都是接口集成工具，主要是为了提供数据功能。类似网易云笔记印象笔记的笔记管理工具。 api 接口管理工具现在，Web 应用的前后端分离事实上已经成为了大家都认可的一种开发方式，前后端分离之后，前端与后端都用接口（api）来沟通，这就需要我们做好 API 接口管理，所以，这次来聊聊 API 接口管理...

marser 2019-08-23 14:43 评论0 收藏0
api 接口管理工具

摘要：接口管理工具大致分为线上工具和自建工具。安装其他工具上面讲的，不管是线上工具还是自建工具，都是接口集成工具，主要是为了提供数据功能。类似网易云笔记印象笔记的笔记管理工具。 api 接口管理工具现在，Web 应用的前后端分离事实上已经成为了大家都认可的一种开发方式，前后端分离之后，前端与后端都用接口（api）来沟通，这就需要我们做好 API 接口管理，所以，这次来聊聊 API 接口管理...

wuyumin 2019-08-16 14:27 评论0 收藏0
swagger系列一：laravel中部署swagger ui

摘要：部署到项目中可以下来也可以下载文件。解压后把目录下的目录拷贝到下下的文件夹中，如新建。访问修改为自己的项目文件。找到，把修改为自己的，如，再次访问即可。但是并不存在，需要生成。如放在下的目录，用于存放文件。 1. 部署swagger ui 到项目中：可以Git下来 git clone https://github.com/swagger-api/swagger-uiv也可以下载zi...

lookSomeone 2019-06-28 18:39 评论0 收藏0