java rest api文档生成_java REST API 文档自动生成 —— springfox-swagger

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