1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面
参考 ：
Swagger介绍及使用 https://www.jianshu.com/p/349e130e40d5
【工具使用】API表达工具----swagger https://blog.csdn.net/zmh458/article/details/78766895
Swagger 常用注解使用详解 https://blog.csdn.net/wyb880501/article/details/79576784
3.0.0 版本及以上（都是使用最新的依赖）
项目中使用 swagger 需要 SpringFox
// 3.0.0 依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
// 2.10.5 springfox-swagger2
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.10.5</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
SpringBoot 集成
新建 SpringBoot Web 项目
导入 springfox-boot-starter 和 ui 的依赖
编写 Hello 工程
配置 Swagger -----> SwaggerConfig
这样只是使用 Swagger2 默认值 ，开启 Swagger2 使用 @EnableOpenApi , 3.0.0以下 使用 @EnableSwagger2
package com.yuanhy.demoswagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration;
import springfox.boot.starter.autoconfigure.SwaggerUiWebMvcConfigurer;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;
import java.util.ArrayList;
import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
/**
* @author yuanhy
* @date 2020-12-19 16:30
*/
@Configuration
@EnableOpenApi //开启 Swagger2
public class SwaggerConfig {
}
package springfox.boot.starter.autoconfigure;
import org.springframework.util.StringUtils;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
// tag::swagger-ui-configurer[]
public class SwaggerUiWebMvcConfigurer implements WebMvcConfigurer {
private final String baseUrl;
public SwaggerUiWebMvcConfigurer(String baseUrl) {
this.baseUrl = baseUrl;
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
String baseUrl = StringUtils.trimTrailingCharacter(this.baseUrl, ‘/‘);
registry.
addResourceHandler(baseUrl + "/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
.resourceChain(false);
}
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController(baseUrl + "/swagger-ui/")
.setViewName("forward:" + baseUrl + "/swagger-ui/index.html");
}
}
// end::swagger-ui-configurer[]
http://localhost:8080/swagger-ui/ 根据源码，这样也是可以的
//配置 Swagger docket bean 实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("yuanhy", "http://localhost:8080/swagger-ui/index.html", "xxx@163.com");
return new ApiInfo(
"yuanhy Swagger Api 文档",
"Api Documentation",
"v1.0",
"http://localhost:8080/swagger-ui/index.html",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
public class RequestHandlerSelectors {
private RequestHandlerSelectors() {
throw new UnsupportedOperationException();
}
//调用 any方法，表示扫描所有接口
public static Predicate<RequestHandler> any() {
return (each) -> {
return true;
};
}
//调用 none 方法，表示所有接口不扫描
public static Predicate<RequestHandler> none() {
return (each) -> {
return false;
};
}
//withMethodAnnotation 基于方法注解扫描
public static Predicate<RequestHandler> withMethodAnnotation(final Class<? extends Annotation> annotation) {
return (input) -> {
return input.isAnnotatedWith(annotation);
};
}
//withClassAnnotation 基于Class 注解扫描
public static Predicate<RequestHandler> withClassAnnotation(final Class<? extends Annotation> annotation) {
return (input) -> {
return (Boolean)declaringClass(input).map(annotationPresent(annotation)).orElse(false);
};
}
package com.yuanhy.demoswagger;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author yuanhy
* @date 2020-12-19 18:39
*/
@RestController
public class MirrorController {
@GetMapping("/mirror")
public String mirror(){
return "mirror";
}
}
any 方法，期待结果是 controller 包中的 HelloController 和非 controller 包中的 MirrorController 都出现在 Swagger UI 上
none 方法，期待结果是 所有接口都不出现在 Swagger UI 上
basePackage("com.yuanhy.demoswagger.controller") 基于 controller 包扫描，期待的结果只有 HelloController 出现在 UI 上
其他的情况也是一样，不再测试了
需求 ： 当配置为生产环境 prod，不允许开启 Swagger ，当为开发环境 dev，允许开启 Swagger
application.properties
spring.profiles.active=dev
application-dev.properties 开发环境
server.port=8081
application-prod.properties 生产环境
server.port=8082
//判断监听配置的 profiles 文件是否是 dev ,是的话，返回 true ,将结果作为设置启动 Swagger 的参数，如下面的 enable
Profiles profiles = Profiles.of("dev");
boolean flag = environment.acceptsProfiles(profiles);
new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable 为 false 表示不启用 Swagger
.enable(flag)
@Bean
public Docket docket(Environment environment){
//需求 当配置为生产环境 prod，不允许开启 Swagger ，当为开发环境 dev，允许开启 Swagger
Profiles profiles = Profiles.of("dev");
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable 为 false 表示不启用 Swagger
.enable(flag)
.select()
/**RequestHandlerSelectors 配置要扫描的接口方式
* basePackage 扫描的包
* 调用 any方法，表示扫描所有接口
* 调用 none 方法，表示所有接口不扫描
* withMethodAnnotation 基于方法注解扫描 （GetMapping.class）
* withClassAnnotation 基于Class 注解扫描 (RestController.class)
* **/
.apis(RequestHandlerSelectors.basePackage("com.yuanhy.demoswagger.controller"))
//在 apis 基础上过滤
//.paths(PathSelectors.ant("/yuanhy"))
.build();
}
当使用生产环境时，结果为不开启 Swagger,如下图
配置 API 文档分组
@Bean
public Docket docket(Environment environment){
//需求 当配置为生产环境 prod，不允许开启 Swagger ，当为开发环境 dev，允许开启 Swagger
Profiles profiles = Profiles.of("dev");
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("yuanhy")
//enable 为 false 表示不启用 Swagger
.enable(flag)
.select()
/**RequestHandlerSelectors 配置要扫描的接口方式
* basePackage 扫描的包
* 调用 any方法，表示扫描所有接口
* 调用 none 方法，表示所有接口不扫描
* withMethodAnnotation 基于方法注解扫描 （GetMapping.class）
* withClassAnnotation 基于Class 注解扫描 (RestController.class)
* **/
.apis(RequestHandlerSelectors.basePackage("com.yuanhy.demoswagger.controller"))
//在 apis 基础上过滤
//.paths(PathSelectors.ant("/yuanhy"))
.build();
}
? 多个分组,增加以下 docket bean 配置，可以在以下图片箭头处切换查看不同分组的接口文档，适用多人开发分类
@Bean
public Docket docketA() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("docketA");
}
@Bean
public Docket docketB() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("docketB");
}
@Bean
public Docket docketC() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("docketC");
}
实体类配置
准备一个实体类User
package com.yuanhy.demoswagger.pojo;
/**
* @author yuanhy
* @date 2020-12-19 19:44
*/
public class User {
private String userName;
private String password;
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
准备一个接口 UserController
package com.yuanhy.demoswagger.controller;
import com.yuanhy.demoswagger.pojo.User;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author yuanhy
* @date 2020-12-19 19:46
*/
@RestController
public class UserController {
//接口中使用实体类，才会在 Swagger 的 Models 看得到
@PostMapping("/user")
public User getUser(){
return new User("yuanhy","123456");
}
}
@ApiModel 对实体类说明，@ApiModelProperty 对实体类属性说明
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
private String userName;
@ApiModelProperty("密码")
private String password;
public User(String userName, String password) {
this.userName = userName;
this.password = password;
}
}
@ApiOperation 定义接口方法用途 ，@ApiParam 定义方法参数含义
@ApiOperation("对某个用户说 Hello")
@GetMapping("/helloUser")
public String sayHelloToUserNme(@ApiParam("用户名") String userName) {
return "Hello, " + userName;
}
原文：https://www.cnblogs.com/yuanhy/p/14162326.html