接口文档管理一直是一个让人头疼的问题，伴随着各种接口文档管理平台涌现，如阿里开源的rap，ShowDoc，sosoapi，等等。这些平台都是一个共同特点，创建文档，编辑，保存文档，一些功能强大的还有mock，统计接口信息等功能，所以这些平台更像一个接口文档的存储管理系统，可以方便人们查看、编辑文档。然而接口一般都是经常变化，这就需要接口编写者及时更新文档，否则文档将失去意义，但是频繁去更新文档也会花费开发不少时间。Swagger的出现在某种程度上解决了这些问题，Swagger提供了一套完整的接口文档解决方案，其功能非常强大，下面将从Swagger简单介绍和使用、Swagger-springmvc原理解析、Swagger其他功能等方面介绍。
Swagger介绍和使用
什么是通达信交易接口,swagger
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。官方网站：http://通达信交易接口,swagger.io/。
Swagger采用OpenAPI规范，OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出。一旦编写完成，API文档可以作为：
·需求和系统特性描述的根据
·前后台查询、讨论、自测的基础
·部分或者全部代码自动生成的根据
·其他重要的作用，比如开放平台开发者的手册
如何编写API文档
定义YAML文件，然后可以生成各种语言的代码框架，对于后台程序员来说，较少人会愿意写出一堆YAML格式。
定义JSON格式文件，按照通达信交易接口,swagger文档书写规范编写文档，和YAML一样只是两种不同格式。
Springmvc项目中使用通达信交易接口,swagger
添加maven依赖
com.mangofactory
通达信交易接口,swagger-springmvc
1.0.2
定义一个通达信交易接口,swagger配置类，添加如下注解，具体内容可参考网上demo
在spring配置文件中将写的config类添加一个bean
在controller中接口处添加通达信交易接口,swagger注解和相应参数
SwaggerUI配置
修改通达信交易接口,swagger/index.html文件，默认是从连接http://petstor通达信交易接口,swagger.io/v2/通达信交易接口,swagger.json获取API的JSON，这里需要将url内容修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的内容根据具体情况填写。比如本文的url值为：http://localhost/quality/docs/api-docs。所有工作完成后，在浏览器中输入上述url地址可得到如下页面。
接口详情如下所示：
可以根据请求参数访问接口，如果网络通畅将返回接口的response结果，在该页面可以看到接口的基本详情，而且如果后台接口发生变化，该页面中的信息也会随着变化，这样接口的内容就是实时变化的，相对于静态的文档每次改动都需要开发更新文档的方式，该方式无疑是非常好的解决方案。
如果过程中发现没有达到预期的结果，请检查通达信交易接口,swaggerui位置是否正确；spring中是否添加了SwaggerConfig的bean。
Springboot项目中使用通达信交易接口,swagger2
相对于springmvc中添加通达信交易接口,swagger，springboot中更加简单。Springboot中许多配置是默认的，不用太多配置就能完成通达信交易接口,swagger的接入。具体流程如下：
添加maven依赖
io.springfox
springfox-通达信交易接口,swagger2
2.2.2
io.springfox
springfox-通达信交易接口,swagger-ui
2.2.2
创建通达信交易接口,swagger2配置类，该类和springmvc中的不太一样，具体可参考通达信交易接口,swagger官网。配置中通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger
和springmvc一样，在controller接口中编写通达信交易接口,swagger相关的注解来标识接口信息。如下所示，通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
完成上述代码添加上，启动SpringBoot程序，访问：http://localhost:8080/通达信交易接口,swagger-uhtml。就能看到前文所展示的RESTfulAPI的页面。我们可以再打开具体的API请求，以POST类型的/users请求为例，可找到上述代码中我们配置的Notes信息以及参数user的描述信息，如下所示。
通过简单的配置改动，spring就能结合通达信交易接口,swagger，通过简单的方式自动生成接口文档，而且以可视化页面的形式展现，非常灵活方便。
下面对通达信交易接口,swagger在spring中使用的一些常用注解进行说明：
Api、ApiIgnoreApiModelApiModelPropertyApiOperationApiParam、ApiImplicitParam、ApiImplicitParamsApiResponseApiResponsesResponseHeader
Api注解用于类上，说明该类的作用。可以标记一个Controller类做为通达信交易接口,swagger文档资源。与Controller注解并列使用。
属性如下：
ApiOperation注解，用在方法上，说明方法的作用，与Controller中的方法并列使用。
ApiParam注解用在@ApiImplicitParams的方法里边，属性配置：
ApiResponse注解用于响应配置，与Controller中的方法并列使用。属性配置：
ApiResponses注解中包含ApiResponse，用于描述一组ApiResponse值。
ResponseHeader注解用于设置响应头，与Controller中的方法并列使用。属性配置：
ApiImplicitParams注解用于方法上包含一组参数说明。
ApiImplicitParam注解用于描述请求参数，根据不同的paramType类型，请求的参数来源不同。属性及取值如下：
ApiModel注解用于表示对类进行说明，描述一个Model的信息，表示参数用实体类接收。
0）ApiModelProperty注解用于方法、字段，表示对model属性的说明或者数据操作更改，配合ApiModel一起使用。
ApiIgnore注解用于类或方法上，表示不需要通达信交易接口,swagger处理。
Swagger提供的注解还有其他一些，此处不做解释，可以通过官方文档或源码查阅，基本常用的注解就是这些，详细的使用方法可以网上查看。如果熟悉了这些注解就可以很快的表示后台代码接口的信息，然后通过页面的形式展示出来。但是通达信交易接口,swagger是如何结合spring通过简单的配置、添加注解的方式就将接口的信息展现出来。下面将看看通达信交易接口,swagger为什么这么神奇。
相关阅读：接口文档神器Swagger
网易云大礼包：https://www.163yucom/gift
相关文章：【推荐】数据挖掘统计分析软件推荐【推荐】网易杭研易盾实习心得
文章为作者独立观点，不代表观点
相关文章
股民评论