1. 导入相关依赖(3.0.0版本)
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.开启Swagger
3.访问Swagger页面:
http://localhost:8080/swagger-ui/index.html#/
4.创建Swagger的配置类,并进行配置
package com.study.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
/**
* 创建Docket类型的对象。并使用spring容器管理。
* DOcket是swagger中的全局配置对象。
* @return
*/
@Bean
public Docket docket(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.select()
.apis(RequestHandlerSelectors.basePackage(""))
.paths(PathSelectors.any())
.build();
//ApiInfo 就是API帮助文档的描述信息。 information
ApiInfo apiInfo =
new ApiInfoBuilder()
.contact( //配置swagger文档主题内容。
new Contact(
"Swagger开发文档", //是文档的发布者名称
"http://www.baidu.com", //是文档发布者的网站地址。企业网站
"123@qq.com") //文档发布者的电子邮箱
)
.title("Swagger框架学习帮助文档")
.description("Swagger框架学习帮助文档详细描述-Swagger框架是一个用于开发RestAPI帮助文档的框架")
.version("1.1")
.build();
//给docket上下文配置api描述信息
docket.apiInfo(apiInfo);
return docket;
}
}
5.swagger2 相关注解说明
1.@Api
说明:用在请求的类上(controller),说明该类的作用
属性:tags=“说明该类的作用”,value=“该参数没什么意义,不需要配置”
示例:@Api(tags = “登陆”)
2.@ApiOperation
说明:用在请求的方法上,说明方法的作用
属性:value=“说明方法的作用”,notes=“方法的备注说明”
示例:@ApiOperation(value=“用户注册”,notes=“手机号,密码都是比输项,年龄限制为数字”)
3.@ApiImplicitParams
说明:用在请求的方法上,包含一组参数说明,@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息
属性:
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)–> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType=“Integer”
defaultValue:参数的默认值
示例:@ApiImplicitParams({
@ApiImplicitParam(name=“mobile”,value=“手机号”,required=true,paramType=“form”),
@ApiImplicitParam(name=“password”,value=“密码”,required=true,paramType=“form”),
@ApiImplicitParam(name=“age”,value=“年龄”,required=true,paramType=“form”,dataType=“Integer”)
})
4. @ApiResponses
说明:用于请求的方法上,表示一组响应,@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
属性:
code:状态码,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
示例:@ApiOperation(value = “select1请求”,notes = “多个参数,多种的查询参数类型”)
@ApiResponses({
@ApiResponse(code=400,message=“请求参数没填好”),
@ApiResponse(code=404,message=“请求路径没有或页面跳转路径不对”)
})
5. @ApiModel
说明:用于响应类上,表示一个返回响应数据的信息
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性