springfox-swagger有什么用?
自动生成restAPI文档
文档在线查看/在线调试
随着代码自动更新
自动生成客户端代码
自动生成server模拟代码
openAPI-specification/swagger/springfox
openAPI-specification 是一套描述REST API的规范
swagger 是实现openAPI-specification的一套工具。是个具体实现
springfox 原名swagger-springmvc 是对swagger的java spring的集成。 目前也可以兼容swagger之外的规范,例如RAML和jsonapi。
swagger 1和 swagger 2的区别
swagger1 指的是 OpenAPI Spec用的是1.2版本
swagger2 指的是 OpenAPI Spec用的是2.0版本
springfox-swagger2 对应的 swagger-core 版本是 1.5.3- 1.5.4
Swagger core Version
Release Date
OpenAPI Spec compatibility
Notes
Status
2.0.0
2018-03-20
3.0
Supported
2.0.0-rc4
2018-01-22
3.0
Supported
2.0.0-rc3
2017-11-21
3.0
Supported
2.0.0-rc2
2017-09-29
3.0
Supported
2.0.0-rc1
2017-08-17
3.0
Supported
1.5.18 (current stable)
2018-01-22
2.0
Supported
1.5.17
2017-11-21
2.0
Supported
1.5.16
2017-07-15
2.0
Supported
1.3.12
2014-12-23
1.2
Supported
1.0.0
2011-10-16
1.0
Deprecated
Prerequisites
You need the following installed and available in your $PATH:
Prerequisites 2.X
You need the following installed and available in your $PATH:
springfox 架构
+------------------+
| | Contains the internal service and
| springfox-core | schema description models along with
| | their builders.
+---------+--------+
^
+---------+--------+
| | Contains the service provider interfaces that
| springfox-spi | can be used to extend and enrich the service models.
| | For e.g. swagger specific annotation processors.
+---+------+----+--+
^ ^ ^
+---------------+----+ | +--+------------------+
Schema inference | | | | | spring web specific extensions that can build
extensions that help | springfox-schema | | |springfox-spring-web | the service models based on RequestMapping
build up the schema for| | | | | information. This is the heart library that
the parameters, models +--------------------+ | +---------------------+ infers the service model.
and responses |
+------------+-------------+
| | Common swagger specific extensions
| springfox-swagger-common | that are aware of the different
| | swagger annotations.
+-----+---------------+----+
^ ^
+-------------+----+ +----+--------------+
| | | | Configurations, and mapping layer
|springfox-swagger1| |springfox-swagger2 | that know how to convert the
| | | | service models to swagger 1.2 and
+------------------+ +-------------------+ swagger 2.0 specification documents. A
Also contains the controller for each
of the specific formats.
springfox-swagger2
引入jar包
io.springfox
springfox-swagger2
2.x.x
io.springfox
springfox-swagger-ui
2.x.x
全局配置boot
@SpringBootApplication
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Bean
public Docket testApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("API接口")
.description("api")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.groupName("default")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")
.select()
.build()
.apiInfo(apiInfo);
}
}
全局配置非boot
@Configuration
@EnableWebMvc
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Bean
public Docket testApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("API接口")
.description("api")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.groupName("default")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")
.select()
.build()
.apiInfo(apiInfo);
}
}
配置controller
@Api(tags = {"测试组"})
@RestController
public class Controller {
@ApiOperation(value = "方法1", notes = "方法1描述")
@RequestMapping(value = "/CH070", method = {RequestMethod.POST}
, produces = {"application/json","application/xml"})
public Response method1(@ApiParam(required = true, value = "参数1")
@RequestParam(value = "method11") String method2
, @ApiParam(required = true, value = "method2")
@RequestParam(value = "method2", required = true) String method2) {
}
}
集成 spring-data-rest / bean-validators
io.springfox
springfox-bean-validators
${springfox.version}
io.springfox
springfox-data-rest
${springfox.version}
@Import({SpringDataRestConfiguration.class, BeanValidatorPluginsConfiguration.class})
springfox-swagger-ui
swagger-ui 是一个node工程,通过swagger暴露的接口,展示文档信息
springfox-swagger-ui 是一个webjar, 方便进行maven集成
springfox-ui 目录结构:
```
META-INF
|- resources
|- webjars
|-swagger-ui.html
|-springfox-swagger-ui
|-css
|-fonts
|-images
|-lang
|-lib
|-o2c.html
|-springfox.js
|-swagger-ui.min.js
```
什么是webjar?
第三方小工具, 把静态资源进行打包,幷版本化管理。
spring-boot 默认支持。
//WebMvcAutoConfiguration#addResourceHandlers
if (!registry.hasMappingForPattern("/webjars/**")) {
customizeResourceHandlerRegistration(
registry.addResourceHandler("/webjars/**")
.addResourceLocations(
"classpath:/META-INF/resources/webjars/")
.setCachePeriod(cachePeriod));
}
非spring-boot
其他风格的替代品:
swagger-codegen
swagger-codegen这个是总入口。不过文档比较乱,不太好找,下面列出几个关键点
从哪里获得输入的配置文件?
springfox-swagger-ui 默认输出地址为/v2/api-docs?group=default。
group可以自定义,default group可以不传。 通过浏览器地址栏请求可能无法接受json格式的返回报文,这时可以通过更改spring-boot配置项springfox.documentation.swagger.v2.path 添加后缀解决,例如:/v2/api-docs.json
#springfox.documentation.swagger2.web.Swagger2Controller
public static final String DEFAULT_URL = "/v2/api-docs";
@RequestMapping(
value = DEFAULT_URL,
method = RequestMethod.GET,
produces = { APPLICATION_JSON_VALUE, HAL_MEDIA_TYPE })
@PropertySourcedMapping(
value = "${springfox.documentation.swagger.v2.path}",
propertyKey = "springfox.documentation.swagger.v2.path")
@ResponseBody
public ResponseEntity getDocumentation(
@RequestParam(value = "group", required = false) String swaggerGroup,
HttpServletRequest servletRequest) {
具体有哪些配置项 源码 文档没怎么说,源码里有列表。。
模拟Server Server stub generator HOWTO 包括spring-boot和Spring MVC