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
