java REST API 文档自动生成 —— springfo
2018-04-02 本文已影响938人
黄大海
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 | tag v2.0.0 | Supported |
| 2.0.0-rc4 | 2018-01-22 | 3.0 | tag v2.0.0-rc4 | Supported |
| 2.0.0-rc3 | 2017-11-21 | 3.0 | tag v2.0.0-rc3 | Supported |
| 2.0.0-rc2 | 2017-09-29 | 3.0 | tag v2.0.0-rc2 | Supported |
| 2.0.0-rc1 | 2017-08-17 | 3.0 | tag v2.0.0-rc1 | Supported |
| 1.5.18 (current stable) | 2018-01-22 | 2.0 | tag v1.5.18 | Supported |
| 1.5.17 | 2017-11-21 | 2.0 | tag v1.5.17 | Supported |
| 1.5.16 | 2017-07-15 | 2.0 | tag v1.5.16 | Supported |
| 1.3.12 | 2014-12-23 | 1.2 | tag v1.3.12 | Supported |
| 1.2.4 | 2013-06-19 | 1.1 | tag swagger-project_2.10.0-1.2.4 | Deprecated |
| 1.0.0 | 2011-10-16 | 1.0 | tag v1.0 | Deprecated |
-
Prerequisites
You need the following installed and available in your $PATH:
- Java 7 (http://java.oracle.com)
- Apache maven 3.0.4 or greater (http://maven.apache.org/)
-
Prerequisites 2.X
You need the following installed and available in your $PATH:
- Java 8 (http://java.oracle.com)
- Apache maven 3.0.4 or greater (http://maven.apache.org/)
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包
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.x.x</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.x.x</version> </dependency> -
全局配置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
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>${springfox.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-data-rest</artifactId> <version>${springfox.version}</version> <dependency>@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
<mvc:resources mapping="/swagger-ui.html" location="classpath:/META-INF/resources/"/> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
其他风格的替代品：
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<Json> getDocumentation( @RequestParam(value = "group", required = false) String swaggerGroup, HttpServletRequest servletRequest) { -
在线生成 https://generator.swagger.io/ 貌似需要把配置文件暴露到外网
-
swagger-codegen-maven-plugin maven 自动化集成
-
具体有哪些配置项 源码 文档没怎么说，源码里有列表。。
-
模拟Server Server stub generator HOWTO 包括spring-boot和Spring MVC
