数码吧

基于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
@EnableSwagger2
public 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 = "用户接口")
@RestController
public 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);
    }
}

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();
    }
}

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);
    }

}