创建工程
创建一个 Spring Boot 工程，加入 web 依赖，工程创建成功后，加入 Swagger2 相关依赖（springfox-swagger2、springfox-swagger-ui）。
Maven 仓库地址：https://mvnrepository.com/
1、导入依赖
<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>
2、创建一个 SwaggerConfig 类
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
// 配置了Swagger的Docket的bean实例
@Bean
public Docket createDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置API文档的分组
.groupName("Api-Groupg")
.select()
.apis(RequestHandlerSelectors.basePackage("com.swagger2.controller"))
.build();
}
// 配置Swagger信息=apiInfo
private ApiInfo apiInfo() {
// 作者信息
Contact contact = new Contact("名字", "https://www.baidu.com/", "邮箱");
return new ApiInfo(
"这是我的SwaggerAPI文档",
"接口文档",
"1.0",
"https://www.baidu.com/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
/**
* Swagger2配置信息
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("webApi")
.apiInfo(webApiInfo())
.select()
//只显示api路径下的页面
.paths(Predicates.and(PathSelectors.regex("/api/.*")))
.build();
}
@Bean
public Docket adminApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("adminApi")
.apiInfo(adminApiInfo())
.select()
//只显示admin路径下的页面
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))
.build();
}
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
.title("网站-API文档")
.description("本文档描述了网站微服务接口定义")
.version("1.0")
.contact(new Contact("atguigu", "http://atguigu.com", "[email protected]"))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("后台管理系统-API文档")
.description("本文档描述了后台管理系统微服务接口定义")
.version("1.0")
.contact(new Contact("atguigu", "http://atguigu.com", "[email protected]"))
.build();
}
}
3、添加注解
@Api：用在 请求的类 上，表示 对类的说明
tags="说明该类的作用，可以在UI界面上看到注解"
value="参数无意义，不配置也可在UI界面上看到"
@ApiOperation：用在 请求的方法 上，说明 方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在 请求的方法 上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
@ApiModel：用在 响应的类（实体类） 上，表示返回响应数据的信息
@ApiModelProperty="用在 属性 上，描述 响应类的属性"