2018-11-21 · Develop

SpringBoot 集成 Swagger2

前后端分离早已经不是新闻,当真正分离之后确遇到了更多问题。

谢小呆的文章 为什么前后端分离了,你比从前更痛苦? 很好的阐述了这种现象和解决方案。

今天我们使用 Swagger 与 SpringBoot 进行集成来很好的解决第二点接口文档永远都是不对的,Swagger是通过一套反射机制从代码中生成文档,并且借助ajax可以直接在文档中对API进行交互。因为代码与文档是捆绑的所以在迭代代码的时候,就能方便的将文档也更新了。不会出现随着项目推移代码与文档不匹配的问题。

swagger 是一个流行的 API 开发框架,这个框架以“开放 API 声明”(OpenAPI Specification,OAS)为基础, 对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。Swagger 官网 https://swagger.io/

swagger-logo

下面是 Swagger 的生态图

swagger-ecology

简单使用 Swagger

1 - 创建 Spring-Boot 应用

这里不是讲述 Spring-Boot 的文章,所以说下使用 Spring-Boot 版本就行

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.0.5.RELEASE</version>
    <relativePath/>
</parent>

2 - 引入相关依赖

这里使用 Maven 作为依赖管理,所以配置 pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>

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

3 - 编写配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Default")
                .apiInfo(apiInfo())
                .select()
                // .apis(RequestHandlerSelectors.basePackage())
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX系统API接口文档")
                .description("aaaa/bbbb/cccc/dddd/====")
                .version("1.0.0")
                .build();
    }
}

4 - 开始编写 Controller 文档

@RestController
@RequestMapping("/app")
@Api("Hello 测试API")
public class HelloController {

    @GetMapping("/hello")
    @ApiOperation("返回名字")
    public String hello(@ApiParam("名称") @RequestParam String name) {
        return "Hello, " + name;
    }
}

其中使用的 Swagger 相关注解,留待下篇文章讲解。。。

5 - 启动项目测试

启动项目后,访问 http://localhost:8080/swagger-ui.html 将会看到如下的界面

swagger-hello-index

点开 API 可以对其进行在线测试

swagger-hello-try-it-out

6 - 文档开关

这样的 API 文档和代码的耦合度比较高,如何实现在生产环境下,关闭 swagger 的功能呢?其实 swagger 已经想到了这个问题,我们只需添加一个变量开控制就好

swagger:
  enable: false
    @Value("${swagger.enable}")
    private boolean swaggerEnable;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
    ...