springboot 中配置 swagger 自动生产 api 文档

swagger 是比较好的 Restful api 文档生成工具。本文教大家在 springboot 中配置注解,以生成 api 文档,省去手写 json 或者 yaml 的麻烦。 smile

首先添加 maven 相关依赖。

<dependency>
     <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.13</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0<version/>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.1</version>
</dependency>

springfox-swagger2 和 swagger2markup 使用的 guava 包 比较老。可能会有兼容问题。如果项目中使用 google 的 guava ,记得把这两个包中的 guava 包 剔除。
然后配置 swagger

@Configuration
@EnableSwagger2
public class Swagger {
    @Bean
  public Docket swaggerSpringMvcPlugin() {
        ApiInfo apiInfo = new ApiInfo("测试文档", "相关介绍", "1.0-SNAPSHOT", null, null, null, null);
        Docket docket = new Docket(DocumentationType.SWAGGER_2).select().paths(s -> true).build()
                .apiInfo(apiInfo).useDefaultResponseMessages(false);
        return docket;
    }
}

接着就可以使用 swagger 注解,添加我们的 api 文档啦。
先在 controller 上添加 api 注解, 添加 api 描述

@Api(value = "构建相关接口", tags = "build")
@RestController
@RequestMapping("/api/v1")
public class BuildService {

在对应的方法上

@ApiOperation(value="一个测试API",notes = "第一个测试api")
@ResponseBody
@RequestMapping(value = "/hello",method = RequestMethod.GET) 
public String hello(){ 
      return "hello";
 }

添加参数描述等

public void test(@ApiParam(value = "id",  required = true) Long id){

查看接口文件和文档

若是没有问题,现在可以部署项目,并打开http://localhost:8080/v2/api-docs:

Firefox 提供了查看 JSON 的插件,推荐大家搜索试试看。

废话不多说,这里可以看到之前配置的诸多信息。注入 description,version,title 等。

最后,我们打开http://localhost:8080/swagger-ui.html,便可以看到一个漂亮的界面了:

参考文档

http://springfox.github.io/springfox/docs/current/
http://springfox.github.io/springfox/javadoc/current/