Last week saw someone mention one issue in my Github open source projects that consider whether access swagger. Well, today I use swagger to do comparison with other interface documentation tool, but to talk about that point Api interface documentation tool thing. Today, the final end of this decade the development front, Api interface documentation management tools become more and more important. Api before and after the complete interface documentation can greatly enhance the efficiency of terminal development collaboration.
What are the current market relatively good interface to document management tool? Swagger Api interface documentation tool in the end how, I generally summary about it!
一、Swagger
Speaking of Swagger, he really is an artifact developer invents, he can automatically generate API interface documentation, on-line debugging, very convenient. Swagger official document: https://swagger.io/ . Project Access: pom-dependent:
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> Configuration information:
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter { @Bean public Docket buildDocket() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()); docket = docket.select() .apis(RequestHandlerSelectors.any())//controller路径 .paths(PathSelectors.any()).build(); return docket; } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } private ApiInfo buildApiInf() { return new ApiInfoBuilder() .title("RestAPI Docs") .termsOfServiceUrl("http://www.github.com/kongchen/swagger-maven-plugin") .build(); } } Controller in the configuration (for example):
@Api(value="客户API",tags={"客户API"})
@RestController
@RequestMapping("/api/customer/") public class CustomerController { /** * 更新采购商资料 * * @return * @throws Exception */ @ApiOperation(value="更新商户信息", notes="根据Customer对象更新,SON格式：{\"id\":1,\"customerType\":\"..\",...}") @ApiImplicitParam(name = "Json", value = "", dataType = "Json",required = true) @ResponseBody @RequestMapping(value="update", method=RequestMethod.POST, produces = {"application/json;charset=UTF-8"}) public JSONObject updateCustomer(HttpServletRequest request) throws Exception{ //TODO 代码逻辑 } } Start the project, open swagger, interface: http://192.168.1.101:9001/swagger-ui.html ,
Just look at the interface configuration:
Swagger particularly easy access, also available online debugging. Swagger then it certainly is very fast hardware, we look at his strengths and weaknesses.
Swagger advantages as follows:
1, saving a lot of time handwriting interface documentation, which is the biggest advantage;
2, the document can be generated directly interface line test, save the setting process using Postman interface parameters, and the parameters of the request, the parameters return glance;
3, the interface module has been classified according to the display, clear structure;
**** Swagger disadvantages as follows:
1, need to write a lot of notes in the code generated interface documentation more clear, more written comments;
Case 2, for complex functions, a function requires multiple modules together, let the FBI test will be a very troublesome thing. Swagger does not support custom interface document not indicate a need to use a function which interfaces;
3、对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map)，就无法实现给每一个返回字段的说明；
4、无法测试错误的请求方式、参数等。如接口指定使用 POST 请求，则无法使用 swagger 测试 GET 请求的结果，也无法自定义 Header；
5，分布式开发环境中，一个项目往往有多个接口服务（比如电商项目有app，pc，后台三个接口服务）。每一个接口服务都对应一个独立的swagger文档，不能实现统一整合。
二，apizza
Apizza也是我们项目中使用过的，是从Swagger 转到Apizza。而却他是极客专属的api协作管理工具，免费的团队协作，在线模拟调试，快速生成api文档，导出离线版文档。
项目Api接入：
只需在Apizza官网（https://apizza.net）申请账号，创建项目，并手写添加接口文档。
主要功能
-
api跨域调试量身定制的chrome插件，本地，在线接口，都可以调。
-
云端存储，企业安全版支持本地数据中心。
-
一键分享，与团队共享你的API文档。
-
支持Postman，Swagger格式 导入Postman/Swagger Json 生成文档。
-
导出离线文档，部署本地服务器。
-
api Mock 根据文档自动生成返回结果，提供独立URL方便前端测试。
-
支持多种文档 http接口文档，markdown说明文档。
Apizza接口文档工具有一个很大不足的地方，那是Apizza个人免费版有人数****限制，所有超过8人的团队如果想免费用，你是不用考虑Apizza的。如果你看到有文章或公众号上说Apizza是免费的，那简直是胡扯，他肯定没用过。当然如果你不缺钱，可以付费开通企业版。我们团队也是用了半年多Apizza，后来由于人员增加，Apizza里又无法再新添加新成员，迫使我们不得不放弃Apizza。
三，Yapi
Yapi是去哪儿网开源的一款接口管理工具。Yapi旨意将接口作为一个公共的可视化的方式打通前端、后台、测试环节，整合在一块，共同使用维护，提高接口的维护成本。Yapi是一款免费开源的Api接口文档工具，需要下载部署在自己的服务器上。Yapi也是我们现在正在使用的接口文档工具。
主要特点如下：
- 权限管理 YApi 成熟的团队管理扁平化项目权限配置满足各类企业的需求；
- 可视化接口管理 基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率；
- Mock Server 易用的 Mock Server，再也不用担心 mock 数据的生成了；
- 自动化测试 完善的接口自动化测试,保证数据的正确性；
- 数据导入 支持导入 swagger, postman, har 数据格式，方便迁移旧项目；
- 插件机制 强大的插件机制，满足各类业务需求；
Here's installed on Yapi not described in detail. Yapi need to install pre-installed nodejs, mongodb, git application. Today we talked mainly used Api interface documentation tools, on the whole, these three individuals feel pretty good. In very young team, that can meet the actual demand. However, when the number of teams increased slowly, we need to consider some of the limitations of the tool, which is the reason we Yapi then from Swagger to Apizza. Of course, in addition to the above three, the market there are many other Api documentation tool. Such as: eoLinker, ShowDoc, easydoc, MinDoc like. Having said that, that specific use, which one do? This need to choose a most suitable for their own situation according to their own teams.
Scan code number of public attention, send keyword obtaining relevant information:
-
Send "Springboot" real source projects receive electricity supplier;
-
Send "SpringCloud" cloud receive real learning materials;