1 简介
官网：https://swagger.io/
- Swagger 是一套功能强大且易于使用的 API 开发人员工具套件，适用于团队和个人，支持从设计和文档到测试和部署的整个 API 生命周期的开发。
- Swagger 包含开源、免费和商用工具的组合，允许任何人，从技术工程师到街头智能产品经理，构建每个人都喜欢的令人惊叹的 API。
- Swagger 由 SmartBear Software 构建，SmartBear Software 是团队软件质量工具的领导者。SmartBear 支持软件领域的一些知名人士，包括 Swagger、SoapUI 和 QAComplete。
2 Spring Boot整合Swagger
2.1 依赖和配置文件
pom.xml
<!-- web依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- swagger依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- swagger-ui依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
application.properties
server.port=8800
2.2 Swagger配置类
/** * 开启Swagger2 */ @Configuration @EnableSwagger2 public class SwaggerConfig { }
测试：访问http://localhost:8800/swagger-ui.html
2.3 进阶整合配置一
2.3.1 新建Controller
/** * @desc: 控制器 * @author: YanMingXin * @create: 2021/8/2-14:38 **/ @RestController public class StudentController { /** * Hello World * * @return */ @RequestMapping("/hello") public String hello() { return "Hello Swagger"; } }
2.3.2 配置自定义Docket
/** * @desc: Swagger配置 * @author: YanMingXin * @create: 2021/8/2-14:34 **/ @Configuration @EnableSwagger2 public class SwaggerConfig { /** * 配置Docket的bean * * @return */ @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); } /** * 配置文档信息（apiInfo） * * @return */ private ApiInfo apiInfo() { Contact contact = new Contact("Mr.YanMingXin", "https://blog.csdn.net/Mr_YanMingXin", "联系人邮箱/博客"); /** * 参数1：标题 * 参数2：描述 * 参数3：版本 * 参数4：组织链接 * 参数5：联系人信息 * 参数6：许可 * 参数7：许可连接 * 参数8：扩展 */ return new ApiInfo( "Spring Boot 整合 Swagger", "学习Swagger,Spring Boot 整合 Swagger", "v1.0", "https://blog.csdn.net/Mr_YanMingXin", contact, "Apache 2.0 许可", "https://blog.csdn.net/Mr_YanMingXin", new ArrayList<>() ); } }
2.3.3 测试
访问http://localhost:8800/swagger-ui.html
2.4 进阶配置二
2.4.1 配置分组
/** * 创建分组 * * @return */ @Bean public Docket docketByGroupOne() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) // 配置分组 .groupName("GroupOne"); } /** * 创建分组 * * @return */ @Bean public Docket docketByGroupTwo() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) // 配置分组 .groupName("GroupTwo"); }
2.4.2 配置Model
Models的两种前提条件
- @ApiModel注解
- 在Controller的返回值中的返回类型
Student.java
/** * @desc: Student实体类 * @author: YanMingXin * @create: 2021/8/2-14:34 **/ @ApiModel("Student实体类") public class Student { @ApiModelProperty("主键") public Integer sId; /** * private修饰会无效 */ @ApiModelProperty("姓名") private String sName; public Student(Integer sId, String sName) { this.sId = sId; this.sName = sName; } }
StudentController.java
/** * @desc: 控制器 * @author: YanMingXin * @create: 2021/8/2-14:38 **/ @RestController public class StudentController { /** * Hello World * * @return */ @RequestMapping("/hello") public String hello() { return "Hello Swagger"; } /** * 返回一个Student实体类 * * @return */ @RequestMapping("/student") public Student student() { return new Student(1, "zs"); } }
测试：
2.4.3 配置扫描包
/** * 根据注解扫描 * * @return */ @Bean public Docket docketByAnnotation() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("TestStu01") .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口 .apis(RequestHandlerSelectors.basePackage("org.ymx.sp_swagger.controller")) .build(); }
2.4.4 配置Swagger开关
配置分组的开关
@Bean public Docket docketOnOrOff() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("Test02") //配置是否启用Swagger，如果是false，在浏览器将无法访问（只针对于Test02的分组） .enable(false) // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口 .select() .apis(RequestHandlerSelectors.basePackage("org.ymx.sp_swagger.controller")) // 配置如何通过path过滤,即这里只扫描请求以/开头的接口 .paths(PathSelectors.ant("/**")) .build(); }
2.5 进阶配置三
2.5.1 配置皮肤bootstrap-ui
依赖：
<!-- 引入swagger-bootstrap-ui包 /doc.html--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.1</version> </dependency>
访问地址：http://localhost:8800/doc.html
2.5.2 配置皮肤Layui-ui
依赖：
<!-- 引入swagger-ui-layer包 /docs.html--> <dependency> <groupId>com.github.caspar-chen</groupId> <artifactId>swagger-ui-layer</artifactId> <version>1.1.3</version> </dependency>
访问地址：http://localhost:8800/docs.html
2.5.3 配置皮肤mg-ui
依赖：
<!-- 引入swagger-ui-layer包 /document.html--> <dependency> <groupId>com.zyplayer</groupId> <artifactId>swagger-mg-ui</artifactId> <version>1.0.6</version> </dependency>
访问地址：http://localhost:8800/document.html
3 常用注解
| Swagger注解 | 简单说明 |
| @Api(tags = “xxx模块说明”) | 作用在模块类上 |
| @ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
| @ApiModel(“xxxPOJO说明”) | 作用在模型类上：如VO、BO |
| @ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上，hidden设置为true可以隐藏该属性 |
| @ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上，类似@ApiModelProperty |
