springboot使用swagger2生成开发文档
一、引入jar包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
二、创建swagger2的配置类
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi(){
//多个暴露路径时
//com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("com.dingzi.project.Controller");
//com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("com.dingzi.project.apiController");
return new Docket(DocumentationType.SWAGGER_2)
//API基本信息
.apiInfo(apiInfo())
.select()
//暴露路径为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.example.learn.swagger2"))
//多个暴露路径
//.apis(Predicates.or(selector1,selector2))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 测试使用 Swagger2")
//创建人、路径、邮箱
.contact(new Contact("dingzi", "", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
三、使用swagger2注解
@RestController
@RequestMapping("/api")
@Api("swagger2Controller测试api")
@Slf4j
public class SwaggerDemoController {
@Autowired
private UserService userService;
@ApiOperation(value = "根据id查询用户", notes = "查询用户信息")
@ApiImplicitParam(name = "id",value = "用户id",required = true)
@RequestMapping(value = "/getuser/{id}",method = RequestMethod.GET)
public User getUser(@PathVariable String id){
return userService.getUser(id);
}
}
- 在controller上的注解
@Api：用在controller上，表示对类的说明。一般为
@Api("swagger2Controller测试api")
常用参数：
tags="说明该类的作用，非空时将覆盖value的值"
value="描述类的作用"
其他参数：
description 对api资源的描述，在1.5版本后不再支持
basePath 基本路径可以不配置，在1.5版本后不再支持
position 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
produces 设置MIME类型列表（output），例："application/json, application/xml"，默认为空
consumes 设置MIME类型列表（input），例："application/json, application/xml"，默认为空
protocols 设置特定协议，例：http， https， ws， wss。
authorizations 获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
hidden 默认为false， 配置为true 将在文档中隐藏
- 用于方法上（说明参数的含义）
@ApiOperation：方法的说明 一般为
@ApiOperation(value = "根据id查询用户", notes = "查询用户信息")
常用参数：
value="说明方法的用途、作用"
notes="方法的备注说明"
其他参数：
tags 操作标签，非空时将覆盖value的值
response 响应类型（即返回对象）
responseContainer 声明包装的响应容器（返回对象类型）。有效值为 "List", "Set" or "Map"。
responseReference 指定对响应类型的引用。将覆盖任何指定的response（）类
httpMethod 指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
nickname 第三方工具唯一标识，默认为空
produces 设置MIME类型列表（output），例："application/json, application/xml"，默认为空
consumes 设置MIME类型列表（input），例："application/json, application/xml"，默认为空
protocols 设置特定协议，例：http， https， ws， wss。
authorizations 获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
hidden 默认为false， 配置为true 将在文档中隐藏
responseHeaders 响应头列表
code 响应的HTTP状态代码。默认 200
extensions 扩展属性列表数组
2、@ApiImplicitParams、@ApiImplicitParam：方法的参数的说明；@ApiImplicitParam 用于指定单个参数的说明，@ApiImplicitParams包含多个@ApiImplicitParam 一般为
@ApiImplicitParam(name = "id",value = "用户id",required = true)
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
name：参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value：参数的汉字说明、解释
required：参数是否必须传，默认为false [路径参数必填]
paramType：参数放在哪个地方
·header --> 请求参数的获取：
@RequestHeader
·query --> 请求参数的获取：
@RequestParam
·path（用于restful接口）--> 请求参数的获取：
@PathVariable
·body（不常用）
·form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
3、@ApiResponses、@ApiResponse：方法返回值的状态码说明 一般为
@ApiResponse(code = 200, message = "请求成功")；
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
- 用于对象上（当请求数据描述，即
@RequestBody时， 用于封装请求（包括数据的各种校验）数据；当响应值是对象时，即@ResponseBody时，用于返回值对象的描述。）
1、@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述 一般为
@ApiModel(value="用户登录信息", description="用于判断用户是否存在") 参数： value–表示对象名
description–描述
2、@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义 一般为
@ApiModelProperty(value="用户名")
参数： value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
- 用于方法参数上
1、@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 一般为
@ApiParam(name="id",value="用户id",required=true)
参数为：name–参数名
value–参数说明
required–是否必填
