利用 Swagger 生成 Restful API 接口文档

快速上手

对于已有的 spring boot web 项目, 首先引入 springfox-swagger2 依赖.

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

然后, 增加 @EnableSwagger2 注解, 运行 mvn clean spring-boot:run 命令, 从输出中可以看到增加了如下四个接口

/swagger-resources
/swagger-resources/configuration/ui
/swagger-resources/configuration/security
/v2/api-docs

浏览器打开 http://localhost:8080/swagger-resources, 可以看到如下内容

其中 /v2/api-docs 就是 JSON 格式的 API 文档数据路径, /swagger-resources/configuration/ui 是用于 UI 展示的元信息, 这里就不一一展示了.

再引入 UI 依赖

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

重启启动该 spring-boot 项目, 浏览器打开 http://localhost:8080/swagger-ui.html, 就可以看到 API 接口文档啦!

这里的接口文档不仅仅是让你可以查看接口定义, 还能执行请求, 访问 API, 展示返回结果, 而且对于参数的类型和是否必选都贴心地显示出来了, 是不是很方便呢!

个性化设置

Configuration

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("GALAXY 标注后台接口文档")
                .description("内容标注后台, 包括任务分配、标注查询、监控大盘、权限管理等功能")
                .contact(new Contact("Henry", "https://kaiyuanshuwu.com", "henryhyn@163.com"))
                .termsOfServiceUrl("https://kaiyuanshuwu.com")
                .version("1.0")
                .build();
    }
}

设定访问API doc的路由

springfox:
  documentation:
    swagger:
      v2:
        path: /api/api-docs

Swagger 生态

参考文献