<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
配置类
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
/**
* Swagger的配置类
* @author 陈加兵
*
*/
@Configuration
public class SwaggerConfig{
/**
* 创建用户API文档
* @return
*/
@Bean
public Docket createRestUserApi(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("user")
.apiInfo(apiInfo()) //api的信息
.select()
.apis(RequestHandlerSelectors
.basePackage("cn.tedu.mycat.controller")) //添加包扫描
.paths(PathSelectors.any()).build();
}
/**
* 创建API信息
*/
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("api文档的标题") //标题
.description("api文档的描述") //描述
.contact( //添加开发者的一些信息
new Contact("爱撒谎的男孩", "https://chenjiabing666.github.io",
"18796327106@163.com")).version("1.0").build();
}
}
启动类
-
在springBoot的启动类上添加一个注解即可配置成功:
@EnableSwagger2
访问api的路径
-
http://ip/projectName/swagger-ui.html
注解说明
@Api
- 标注在类上,用来对这个类进行说明的
-
如果想要生成文档,必须在类或者接口上标注
- 属性如下:
属性名称 |
备注 |
默认值 |
value |
url的路径值 |
|
tags |
如果设置这个值、value的值会被覆盖 |
|
description
|
对api资源的描述 |
|
basePath |
基本路径可以不配置 |
|
position
|
如果配置多个Api 想改变显示的顺序位置 |
|
produces |
For example, “application/json, application/xml” |
|
consumes |
For example, “application/json, application/xml” |
|
protocols |
Possible values: http, https, ws, wss. |
|
authorizations
|
高级特性认证时配置 |
|
hidden
|
配置为true 将在文档中隐藏 |
@ApiOperation
- 用在API方法上,对该API做注释,说明API的作用
- 不需要多讲,看源码,使用默认的value属性即可,说明该方法的作用
- 属性如下:
value |
url的路径值 |
|
tags |
如果设置这个值、value的值会被覆盖 |
|
notes |
对api资源的描述 |
|
response |
返回的对象, 在文档中点击Model可以获取该配置的内容
|
|
responseContainer |
这些对象是有效的 “List”, “Set” or “Map”.,其他无效 |
|
responseReference |
可以不配置 |
|
httpMethod |
可以接受 “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
|
position |
如果配置多个Api 想改变显示的顺序位置 |
|
produces |
同 Api中的定义 |
|
consumes |
同 Api中的定义 |
|
protocols |
同 Api中的定义 |
|
authorizations |
同 Api中的定义 |
|
hidden |
是否隐藏,true 或者false ,这个可以隐藏后台接口 |
|
code |
http的状态码 默认 200 |
|
extensions |
扩展属性 |
@ApiImplicitParams
- 用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明
-
很重要,这个注解其中包含接口入参的详细说明
- 内容是集合
@ApiImplicitParam
-
用在
@ApiImplicitParams
注解中,也可以单独使用,说明一个请求参数的各个方面
-
详细的属性使用说明如下:
-
name
:属性的字段名称,相当于form表单中的name,这个就是入参的字段
-
dataType
:参数的类型,标识,字符串
-
value
:该参数的描述
-
required
:是否必填,布尔值
-
defaultValue
:缺省值,会在文档中缺省填入,这样更方面造数据,不需要调用接口的去填值了
-
paramType
:指定参数的入参数方式(也就是请求参数的位置),其中有四种常用的,如下: query
path
body
form
paramType属性的详细说明
-
query
:必须要和入参的字段一样,也可以使用 @RequestParam()
指定
-
path
:用于Restful的风格的url,请求的参数写在路径上,如下:
@ApiOperation(value="根据用户Id获取用户信息",response=User.class,hidden=false)
@ApiImplicitParams({
@ApiImplicitParam(paramType = "path", name = "id", dataType="Integer", required = false, value = "用户的id", defaultValue = "1")
})
@GetMapping("/user/get/{id}")
public Object getUser(@PathVariable("id")Integer id){
return new User(id, "陈加兵");
}
body
form
原文
https://chenjiabing666.github.io/2018/10/21/SpringBoot整合Swagger/