SpringBoot Swagger 的使用

1.先说说Swagger的好处

• 整合到Spring Boot中，构建强大RESTful API文档，并且使用简单
• 省去接口文档管理工作，修改代码，自动更新
• Swagger2也提供了强大的页面测试功能来调试RESTful API。

2.使用

swagger使用起来很简单，只需要两步就可以了。

1. 添加pom依赖.

<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. 启动类上添加@EnableSwagger2注解

@SpringBootApplication
@EnableJpaAuditing
@EnableSwagger2
public class TouristApplication {

 public static void main(String[] args) {
   SpringApplication.run(TouristApplication.class, args);
 }

3. 启动项目，访问路径：http://localhost:8080/swagger-ui.html

• 启动访问效果
  

3.Swagger常用注解

• Api：修饰整个类，描述Controller的作用
• ApiOperation：描述一个类的一个方法，或者说一个接口
• ApiParam：单个参数描述
• ApiModel：用对象来接收参数
• ApiProperty：用对象接收参数时，描述对象的一个字段
• ApiResponse：HTTP响应其中1个描述
• ApiResponses：HTTP响应整体描述
• ApiIgnore：使用该注解忽略这个API
• ApiError ：发生错误返回的信息
• ApiImplicitParam：一个请求参数
• ApiImplicitParams：多个请求参数

4.配置

在引入jar包正常启动后, 已经可以正常使用Swagger, 各个属性都提供了默认值, 当然如果需要自己设置一些属性也可以, 配置方式如下

1. yml 文件格式

swagger:
 contact:
   email: 联系邮箱
   name: 联系人暱称
   url: 联系人地址
 title: 标题
 description: 描述
 base-package: 接口所在包路径
 path-type: 接口选择规则类型, 共分为: ALL(所有接口), REGEX(符合正则), ANT(符合路径)

2. JavaBean格式

@Configuration
public class DemoConfig {
   @Bean
   public SwaggerBean swaggerBean() {
       return SwaggerBean.builder()
               .basePackage("com.xxx.xxx")
               .pathType(PathType.ALL)
               .title("标题")
               .termsOfServiceUrl("http://127.0.0.1")
               .license("XXXX")
               .licenseUrl("http://xxx.xx.xx")
               .description("描述")
               .build();
   }
}