swagger ui with springfox

发表于 | 分类于

swagger

The World’s Most Popular Framework for APIs (官方的自我评价^_^)

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务；类似的服务还有api blueprint (基于markdown)

springfox

Springfox的前身是swagger-springmvc,是一个开源的API doc框架，可以将 spring mvc 的 Controller 转换成以 Swagger ui 文档的形式进行展示展现，效果如下图：

依赖

1
2
3
4
5
6
7
8
9
10
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.version}</version>
</dependency>

最新版本查询

config

springfox的配置主要两点：

  1. 通过 @EnableSwagger2 import springfox 和 spring 相关的配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    // 相关源码
    @Import({Swagger2DocumentationConfiguration.class})
    public @interface EnableSwagger2 {
    }


    @Import({ SpringfoxWebMvcConfiguration.class, SwaggerCommonConfiguration.class })
    @ComponentScan(basePackages = {
        "springfox.documentation.swagger2.readers.parameter",
        "springfox.documentation.swagger2.web",
        "springfox.documentation.swagger2.mappers"
    })
    public class Swagger2DocumentationConfiguration {
      @Bean
      public JacksonModuleRegistrar swagger2Module() {
        return new Swagger2JacksonModule();
      }
    }

  2. 生成 springfox Docket bean, 如果你需要针对不同的路径生成多个api doc, 你可以生成多个Docket bean实例

然后通过如下地址进行访问: http://host:port/swagger-ui.html

配置代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("title")
                .description("description")
                .version("version")
                .termsOfServiceUrl("termsOfServiceUrl")
                .contact(new Contact("contact", "", ""))
                .license("license")
                .licenseUrl("licenseUrl")
                .build();

        AlternateTypeRule alternateTypeRule = newRule(
                typeResolver.resolve(DeferredResult.class,
                typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
                typeResolver.resolve(WildcardType.class));

        List<ResponseMessage> responseMessages = Lists.newArrayList(
                new ResponseMessageBuilder().code(500).message("500 internal server error").responseModel(new ModelRef("Error"))
                        .build());

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("group")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.any())
                // custom excludedPathSelector method
                .paths(excludedPathSelector())
                .build().pathMapping("/")
                .directModelSubstitute(Date.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .alternateTypeRules(alternateTypeRule)
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, responseMessages)
                .forCodeGeneration(true);
    }
    
    // other Docket api bean (diff pathMapping)
}

Docket

A builder which is intended to be the primary interface into the swagger-springmvc framework. Provides sensible defaults and convenience methods for configuration. (from Class Comment)

Docket配置说明：

  1. ApiInfo: 看名字就知道大概含义了，是一些和API相关的的标题、版本等描述信息
  2. groupName: 如果你有多个 Docket 实例一般需要制指定 groupName 进行区分，如果只有一个实例可以使用默认
  3. apis: 指定匹配哪些 Controller 生成 api
  4. paths: 比apis更细的力度，匹配request path, 可用于实现 exclude或者include
  5. pathMapping: servlet path mapping
  6. globalResponseMessage: 增加或改变一些全局响应的信息
  7. securitySchemes、securityContexts: 鉴权相关

更多、更详细 Docket 配置见 官方文档

other

  1. security: 鉴权相关

    http://springfox.github.io/springfox/docs/current/#configuring-security-schemes-and-contexts-an-overview

  1. support for JSR-303

    specifically for @NotNull, @Min, @Max, and @Size

    1
    2
    3
    4
    5
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-bean-validators</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    1
    @Import(springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration.class)

  1. plugins

    http://springfox.github.io/springfox/docs/current/#plugins

@Annotations

Swagger 另外为我们提供了 swagger-annotations 包，里面提供了若干注解，帮我我们更好的对API进行描述和说明，大部分注解都很容易理解，多试几次就了解了；下面是比较常用的几个注解:

  1. @ApiIgnore: 这一个比较特殊,由 springfox 提供，用来让我们忽略生成一些API
  2. @ApiOperation: 用于对方法的描述
  3. @ApiParam: 用于对方法参数的描述
  4. @ApiResponse[s]: 用于对请求响应的描述
  5. @ApiModel: 用于对输入输出模型的描述
  6. @ApiModelProperty: 用于对输入输出模型字段的描述

这些注解的使用并不是强制的，如果你对这种侵入性不敏感，建议使用这些注解更好的描述你的API

spring-boot-starter

对于大多数情况下上面这些配置都会是相似的，而且相同的配置策略也更加有利于规范和统一，所以这个时候我们可以借助spring boot提供的 starter 特性进行统一处理

使用的项目只需要依赖这个 starter, 下面我给出一个我的实现，代码地址如下： spring-boot-starter-swagger