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 | <dependency> |
最新版本查询
config
springfox的配置主要两点：
通过
@EnableSwagger2import 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();
}
}生成 springfox Docket bean, 如果你需要针对不同的路径生成多个api doc, 你可以生成多个Docket bean实例
然后通过如下地址进行访问: http://host:port/swagger-ui.html
配置代码如下：
1 |
|
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配置说明：
- ApiInfo: 看名字就知道大概含义了，是一些和API相关的的标题、版本等描述信息
- groupName: 如果你有多个 Docket 实例一般需要制指定 groupName 进行区分，如果只有一个实例可以使用默认
- apis: 指定匹配哪些 Controller 生成 api
- paths: 比apis更细的力度，匹配request path, 可用于实现 exclude或者include
- pathMapping: servlet path mapping
- globalResponseMessage: 增加或改变一些全局响应的信息
- securitySchemes、securityContexts: 鉴权相关
更多、更详细 Docket 配置见 官方文档
other
security: 鉴权相关
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
(springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration.class)
@Annotations
Swagger 另外为我们提供了 swagger-annotations 包，里面提供了若干注解，帮我我们更好的对API进行描述和说明，大部分注解都很容易理解，多试几次就了解了；下面是比较常用的几个注解:
- @ApiIgnore: 这一个比较特殊,由 springfox 提供，用来让我们忽略生成一些API
- @ApiOperation: 用于对方法的描述
- @ApiParam: 用于对方法参数的描述
- @ApiResponse[s]: 用于对请求响应的描述
- @ApiModel: 用于对输入输出模型的描述
- @ApiModelProperty: 用于对输入输出模型字段的描述
这些注解的使用并不是强制的，如果你对这种侵入性不敏感，建议使用这些注解更好的描述你的API
spring-boot-starter
对于大多数情况下上面这些配置都会是相似的，而且相同的配置策略也更加有利于规范和统一，所以这个时候我们可以借助spring boot提供的 starter 特性进行统一处理
使用的项目只需要依赖这个 starter, 下面我给出一个我的实现，代码地址如下： spring-boot-starter-swagger
]]>
