基于Nginx+Spring Boot+Swagger的api文档实践

一.关于API文档的产生方式

本次是针对前后端开发，后端API文档管理的探讨，一般API文档可以选择以下方式构建

1.搭建专门的文档管理系统，由后端开发好接口，然后进入文档系统，CRUD接口文档

2.通过Mock工具，通过填写YAML 格式的文档描述语言，然后生成接口文档，典型的通过swagger-io，还可以生成后端接口mock代码，还有easy mock等

3.后端程序写好接口，通过代码生成器，自动生成API文档，典型的通过sprigfox-swagger

以上方式各有利弊

方式1：首先找到一个面向操作，界面友好的文档系统其实还是蛮困难的，有可能需要自己开发，其次，考虑到人性，程序员都是比较爱偷懒的，你程序写好了，但你很有可能忘了去更新你的接口文档

方式2：现在开发模式以前后端分离为主，为了让前端开发人员不必等待后端实际接口开发完成，前端可以同步地进行，引入接口契约，通过mock工具产生mock接口，基于此类 的方式，一般有填报式的mock工具，如easy mock，还有编写YAML的mock工具，如swagger等，基于这种方式生成的api文档，要求前后端严格遵守契约的定义，各自都需要引入单元测试来保证对契约的履行质量，这样才能保证接口文档的正确性

方式3：这种方式一个很大的优点就是较好的保证api接口的更新，但是也有例外，就是后端人员修改的代码逻辑，但忘了修改api文档的注释。那么这种方式弊端也是显而易 见的，就是对代码的侵入性比较高

二.基于方式3的实践

我这里后端接口是用spring boot来开发的，所以选择了spring fox，它集成了swagger

1.添加Maven依赖

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

2.开启api config配置 ，创建配置类，取名任意，我这里是ApiDocConfig

@Configuration@EnableSwagger2public class ApiDocConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.stingwoh.webdemo.controller"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Web应用演示模块RESTful APIs")                .description("")                .version("1.0")                .build();    }}

3.编写controller，加上注解，就能生成api文档了，具体的注解不清楚的去百度，也可以看我其他关于swagger的博文

@Api(value = "用户接口")@RestControllerpublic class TestController {    @ApiOperation(value = "获取用户列表", notes = "用户列表")    @RequestMapping(value = "/test", method = RequestMethod.GET)    public ResponseEntity<User> test(){        return new ResponseEntity<User>(new User("xiaoshao",20),HttpStatus.OK);    }}

4.通过访问 http://ip:port/v2/api-docs 就能看到生成的文档，只不过它是一个json

5.通过官方的UI界面访问 http://ip:port/swagger-ui.html

其实这就是第一步maven引入的依赖springfox-swagger-ui所产生的

三.继续优化

通过以上步骤就能构建一个基本能用的API DOC了，但是问题也很多，

比如：

1.生产环境不需要显示文档，如果不去掉，可能影响系统性能和安全性

2.每个项目都添加上UI的依赖，修改起来不方便，也不能做到集中修改

3.官方的UI是没有中文版的，不够友好

针对以上几个问题笔者进行了一些优化

1.通过spring profile 控制api文档的输出环境

我的项目有3个环境，分别为dev qa release，通过spring profile 指定ApiDocConfig的加载环境为dev

@Configuration@EnableSwagger2@Profile(value = "dev")public class ApiDocConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.agioe.webdemo.controller"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Web应用演示模块RESTful APIs")                .description("")                .version("1.0")                .build();    }}

这样就可以只在dev开发环境下才能加载api文档了，怎么使用spring profile 请自己百度

2.单独领出来swagger-ui，单独部署，UI通过访问每个项目的 /v2/api-docs来渲染文档界面，去掉springfox-swagger-ui的jar依赖

这里非常感谢这个项目

https://github.com/helei112g/swagger-ui

提供了汉化版

单独部署配置，将项目clone下来后放入 /usr/local/sttatic-web下，我的路径/usr/local/static-web/swagger-ui

修改nginx配置 conf/nginx.conf

server{        listen       80;        server_name  localhost;location / {            root /usr/local/static-web/swagger-ui;            index index.html;                 }}

spring boot 配置全局跨域(建议生产环境关闭)

@Configuration@Proflie(value = "dev")public class CustomCorsConfiguration extends WebMvcConfigurerAdapter {    @Override    public void addCorsMappings(CorsRegistry registry) {        registry.addMapping("/**").allowedOrigins("*")                .allowedMethods("GET", "HEAD", "POST","PUT", "DELETE", "OPTIONS")                .allowCredentials(false).maxAge(3600);    }}