spring boot集成Springfox-Swagger2

一、为什么选择Swagger2

1.接口文档在线自动生成

2.接口在线调试功能

3.文档与代码可以保持同步（因为文档的方法，参数和模型紧密集成到服务端的代码）

二、在线文档

1.添加maven依赖

    io.springfox
    springfox-swagger2
    2.9.2




    io.springfox
    springfox-swagger-ui
    2.9.2

2.Swagger配置类
在项目中创建 一个类名为RestApiConfig的Swagger配置文件 

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.ComponentScan;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableWebMvc

@EnableSwagger2

@Configuration

@ComponentScan(basePackages ="com.hw.one.core.controller")

public class RestApiConfig extends WebMvcConfigurationSupport {

 @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

              .apiInfo(apiInfo())   

              .host("localhost:8080/api")

              .protocols(Sets.newHashSet("https","http"))  

                //.pathMapping("/")

                .select()

                //只生成被Api这个注解注解过的类接口            //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

                //只生成被ApiOperation这个注解注解过的api接口

                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                //生成所有API接口             //.apis(RequestHandlerSelectors.basePackage("com.hw.one.core.controller"))

                .paths(PathSelectors.any())

                .build();

    }



 private ApiInfo apiInfo() {

 return new ApiInfoBuilder()

 .title("ONE基础平台API")

 .description("ONE基础平台在线API文档，主要提供基础平台的所有功能实现接口。")

// .license("稳定版")

//             .termsOfServiceUrl("http://localhost:8080/dist/index.html")

// .contact(new Contact("ONE基础平台","http://192.168.15.246:8025/#/login","[email protected]"))

 .version("2.0.0")

 .build();

    }

}

3.swagger注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用 
@ApiOperation：描述一个类的一个方法，或者说一个接口 
@ApiParam：单个参数描述 
@ApiModel：用对象来接收参数 
@ApiProperty：用对象接收参数时，描述对象的一个字段 
@ApiResponse：HTTP响应其中1个描述 
@ApiResponses：HTTP响应整体描述 
@ApiIgnore：使用该注解忽略这个API 
@ApiError ：发生错误返回的信息 
@ApiImplicitParam：一个请求参数 
@ApiImplicitParams：多个请求参数
 

/**
 * @Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 * @author Y.S.K
 *
 */
@Api(value="/test1", tags="测试接口模块")
@RestController
@RequestMapping("/test")
public class TestSwaggerController {

    /**
     * @ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
     * @return
     */
    @ApiOperation(value="展示首页信息value", notes = "展示首页信息notes")
    @GetMapping("/show")
    public Object showInfo(){
        return "hello world";
    }

    @ApiOperation(value="添加用户信息", notes = "添加用户信息")
    @ApiImplicitParam(name="user", value="User", required = true, dataType = "User")
    @PostMapping("/addUser")
    public Object addUser(@RequestBody User user){
        return "success";
    }

}

4.Controller类配置

通过对类的注解，来规定类的特征。如图：4-1

 

                                                         图4-1

5. 类注解属性说明

1. @Api：修饰整个类，描述Controller的作用，其各属性作用：

属性名称	属性特性描述
value	类概要描述
tags	用于资源或任何其他限定符的逻辑分组。如果设置这个值、value的值会被覆盖
description	对类的详细描述。
basePath	基本路径可以不配置。
position	如果配置多个Api 想改变显示的顺序位置。（已过时）
produces	响应类型定义属性："application/json, application/xml"。
consumes	请求类型定义属性"application/json, application/xml"。
protocols	定义类所使用的协议: http, https, ws, wss。
authorizations	高级特性认证时配置。
hidden	配置为true 将在文档中隐藏该方法。
response	操作相应类型。
responseContainer	声明一个响应容器，可以是 "List", "Set" or "Map"，其他无效。
httpMethod	请求类型："GET", "HEAD", "POST", "PUT", "DELETE","OPTIONS" ， "PATCH"。
code	http的状态码 默认 200。
extensions	扩展属性。

 

 

 

 

 

 

 

 

 

 

 

6.方法注解属性说明

1.@ApiOperation注解：用在方法上，说明方法的作用，其中各属性的含义：
 

属性名称	属性特性描述
value	方法概要描述
tags	用于资源或任何其他限定符的逻辑分组。使用时，覆盖value值。
description	对方法的详细描述。
basePath	基本路径可以不配置。
position	如果配置多个Api 想改变显示的顺序位置，（已过时）。
produces	响应类型定义属性："application/json, application/xml"。
consumes	请求类型定义属性"application/json, application/xml"。
protocols	定义方法所使用的协议: http, https, ws, wss。
authorizations	高级特性认证时配置。
hidden	配置为true 将在文档中隐藏该方法。
response	操作相应类型。
responseContainer	声明一个响应容器，可以是 "List", "Set" or "Map"，其他无效。
httpMethod	请求类型："GET", "HEAD", "POST", "PUT", "DELETE",  "OPTIONS" ， "PATCH"。
code	http的状态码 默认 200。
extensions	扩展属性。

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

2. @ApiImplicitParam的参数说明：
 

属性	取值	属性特性描述
paramType		查询参数类型
	path	以地址的形式提交数据，（用于restful接口）-->请求参数的获取：@PathVariable。
	query	请求参数放置于请求地址。（可以直接使用@RequestParam获取。）
	body	以流的形式提交 仅支持POST。
	header	请求参数放置于Request Header。（可以直接使用@RequestHeader获取。）
	form	以form表单的形式提交 仅支持POST。
dataType		参数的数据类型 只作为标志说明，并没有实际验证。
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3. @ApiParam注解 (本项目暂时未用)

@ApiParam请求属性,使用方式：

public ResponseEntity createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

属性配置：
 

属性名称	属性特性描述
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

 

 

 

 

 

 

 

 

 

 

4. @ApiResponse注解(本项目暂时未用)

@ApiResponse：响应配置，使用方式：

@RequestMapping(value = "/order", method = POST)

@ApiOperation(value = "Place an order for a pet", response = Order.class)

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

属性配置：
 

属性名称	属性特性描述
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

 

 

 

 

 

 

 

 

5. @ApiResponses注解 (本项目暂时未用)

@ApiResponses：响应集配置，使用方式：

@RequestMapping(value = "/order", method = POST)

@ApiOperation(value = "Place an order for a pet", response = Order.class)

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

6. @ResponseHeader注解 (本项目暂时未用)

@ResponseHeader响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

 

属性名称	描述
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

 

 

 

 

 

 

7.其他 (本项目暂时未用)

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@ApiModelProperty：描述一个model的属性。

整合源码  https://github.com/Fly0905/SwaggerOfflineDoc

三、离线文档

I.为什么要有离线文档？

当我们的项目中集成了Swagger，开发时一般只会使用在线文档，但当接口开发完成之后，我们就需要提供一份给接口调用人参考的接口文档，比如html、pdf、word等格式的接口文档。怎么生成这样的文档呢？有一个Github开源项目swagger2markup已经帮我们实现了这个功能，我们拿来用就可以了。大概过程是，首先通过调用本地接口获取项目中描述接口的json数据，然后swagger2markup利用swagger.json生成adoc文档，然后asciidoctor再通过adoc文档生成对应的html和pdf文档。

II.获取项目中用Swagger描述的接口json数据

访问地址：http://localhost:8080/v2/api-docs

在浏览器右键点击另存为swagger.json文件，当然你也可以写个程序从这个接口获取到数据后自动生成json文件。

III.生成adoc文档和生成html或pdf的配置详细步骤

1、下载swagger2markup项目

swagger2markup项目地址：

https://github.com/Swagger2Markup/spring-swagger2markup-demo

点击下载将这个项目下载下来，里面有些文件我们需要用到。

2、复制该项目src目录下的docs目录到我们自己的src目录中

我们需要用到这个目录下的三个文件，其实只需要一个index.adoc，其他两个可以删掉，但删掉之后index.adoc中的include::manual_content1.adoc[] include::manual_content2.adoc[]也要删掉。这里暂时先不管它，直接复制过来即可。

3、复制swagger2markup项目pom文件中的属性和仓库配置

4、复制swagger2markup项目pom文件中的插件配置

有两个插件配置需要复制过来，一个是生成ascciidoc文档的，一个是生成html或pdf文档的，全部复制过来放到自己项目中的pom文件中，什么都不用改。

5、自己项目中的swagger依赖记得配置

6、在${project.build.directory}目录下创建swagger目录并将swagger.json文件放进来

IV、生成html或pdf文档

所有配置完成后，直接在根目录下使用maven test命令，或者使用Eclipse、IDEA工具执行maven test命令，BUILD SUCDESS之后我们可以在target目录下面看到生成的asccidoc目录，里面有我们需要的html或pdf文件。

V、解决生成的pdf文档中的乱码问题

通过上面的方法生成的html文档编码是没问题的，只是pdf文档中有些地方会有乱码，如果直接拿给别人看肯定是不行的，所以我们需要解决这个乱码问题。

1、下载支持中文的主题和字体，粘贴到项目中

2、更改pom文件 中asciidoctor-maven-plugin插件执行配置引用新的字体和主题文件即可

以上配置demo里面都有，包括相应文件

VI、离线文档demo

https://github.com/wangyuanchen/swagger2pdf