一、为什么选择Swagger2
1.接口文档在线自动生成
2.接口在线调试功能
3.文档与代码可以保持同步(因为文档的方法,参数和模型紧密集成到服务端的代码)
二、在线文档
1.添加maven依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
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","scsoft@163.com"))
.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<User> 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