关于接口文档工具的选型记录和swagger2使用

た入场券 2021-12-11 13:57 265阅读 0赞

### 关于接口文档工具的选型记录 ###

*  背景
 *  选型
 *  swagger2 用法
 *   *  集成springboot
     *  swagger静态文档编写
 *  总结

# 背景 #

对于一个项目来讲，接口文档无疑是十分重要的，一是开需求分析阶段写好接口文档能够帮助梳理逻辑，而是开发完成之后可以记录项目，再回头看项目的时候帮助理解。

# 选型 #

记录接口大体有手写word文档和借助文档编写工具2中方式，今天主要讨论使用哪种工具。  
国内的我看了有

*  易文档 [https://easydoc.xyz][https_easydoc.xyz]
 *  apipost [https://www.apipost.cn][https_www.apipost.cn]
 *  rap [https://github.com/thx/RAP][https_github.com_thx_RAP]

这三个用起来感觉是差不多的，上手简单不用手打很多内容。  
担心相比较来讲，易文档是最便捷的，提供接口文档和输入参数的模板功能，还可以一键生成mock。apipost 有个很大的问题就是不能生成mock。

国外的我就看了

*  swagger 使用yml的编写方式编写接口，编写接口文档的速度比以上3个要快，而且支持复用，于是决定尝试使用swagger2版本编写文档

# swagger2 用法 #

## 集成springboot ##

swagger2 有个强大的功能就是可以集成到项目中来。这里有篇文档介绍的很好 [接口文档神器Swagger（上篇）][Swagger]，  
[接口文档神器Swagger（下篇）][Swagger 1]。  
我自己实现了一下，代码如下：  
maven:

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
             </dependency>

配置文件 swagger2config

@Configurable
    @EnableSwagger2
    @Component
    public class Swagger2Config { 
    
        @Bean
        public Docket createRestApi(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            Contact contact = new Contact("honins", "http://wolwo.com", "wolwo@123.com");
            return new ApiInfoBuilder()
                    .title("医易网后台接口")
                    .description("医易网后台接口--包括医生端和患者端")
                    .contact(contact)
                    .version("1.0.0")
                    .build();
        }
    
    }

controller:

@ApiOperation(value = "loginTestWithParam",notes = "测试")
        @RequestMapping(value = "/patient/user/loginTestWithParam", method = RequestMethod.POST)
        public JsonResult patientLoginTestWithParam(
                @ApiParam(value = "员工id")
                @RequestParam(value = "patientId") String patientId,
                @ApiParam(value = "员工openId")
                @RequestParam(value = "openId") String openId,
                @ApiParam(value = "员工实体")
                @RequestBody Patient patient
        ) { 
            return JsonResult.ok("ok");
        }

效果图：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70 1]

而且在这里 ![在这里插入图片描述][20190709112015526.png] 把/v2/api-docs接在项目的地址后可获得json数据，可直接导入到swagger2中！

## swagger静态文档编写 ##

除了集成代码外，swagger还提供了静态文档的编写方式。

*  SwaggerEditor 这是一个swagger文档编辑工具 [http://editor.swagger.io/][http_editor.swagger.io]
 *  SwaggerCodeGen 这是一个代码生成的工具
 *  Swagger Inspector 这是一个测试接口工具，类似postman [https://swagger.io/tools/swagger-inspector/][https_swagger.io_tools_swagger-inspector]
 *  SwaggerHub，这是一个swagger仓库 [https://app.swaggerhub.com/home][https_app.swaggerhub.com_home]  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70 2]  
    这里是 [文档编写文档][Link 1]  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70 3]  
    这么用起来非常方便，但是还存在以下缺点：**例如需要在后台代码中加一些注解，过多的注解造成注解泛滥；接口文档需要等到后台接口写好才能在前端展示，而一般开发可能需要先定义好接口，然后才开始写代码造成的流程混乱；要很深入的了解swagger需要时间和精力，对于忙业务的开发可能觉得不值得在上面花时间学习。**  
    **其实对于这些问题都有很好的办法解决，相比通过简单学习就能方便的获得接口信息而且不用反复更新文档是很值得的一件事。对于接口文档需要等后台开发完才能展示的问题，可以先通过静态的文档书写方式先写文档，之后再通过后台接口方式实现**

# 总结 #

目前我使用的是swagger2 ，而且使用的是静态的文档书写方式，可以在需求时期快速写好文档，而且使用swagger更加有助于后台人员思维的训练和接口的梳理。  
另外看看这两篇文章，写好我很好，还分析了swagger集成spring的原理。[接口文档神器Swagger（上篇）][Swagger]，  
[接口文档神器Swagger（下篇）][Swagger 1]

*  差点忘记了，有个比较悲催的是一般人访问不了swagger

[https_easydoc.xyz]: https://easydoc.xyz
[https_www.apipost.cn]: https://www.apipost.cn
[https_github.com_thx_RAP]: https://github.com/thx/RAP
[Swagger]: https://sq.163yun.com/blog/article/195247750917337088
[Swagger 1]: https://sq.163yun.com/blog/article/195247833444462592
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70]: /images/20211211/1fed18e93d51404a8252cd8410672c48.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70 1]: /images/20211211/2011753c690048e7b2144fad1eb111ba.png
[20190709112015526.png]: /images/20211211/aca69f04f09e4def8a740777916b9ee1.png
[http_editor.swagger.io]: http://editor.swagger.io/
[https_swagger.io_tools_swagger-inspector]: https://swagger.io/tools/swagger-inspector/
[https_app.swaggerhub.com_home]: https://app.swaggerhub.com/home
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70 2]: /images/20211211/51e437040eeb4e4fb93cf01767347b18.png
[Link 1]: https://swagger.io/docs/specification/serialization/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0hvbm55ZWU_size_16_color_FFFFFF_t_70 3]: /images/20211211/8eeae64de5b7435b97bdf19f6fc5e517.png