Swagger-01-快速入门

2023-10-22 09:32:58

Swagger

1 使用Swagger

需要依赖：

swagger2
UI

1.1 SpringBoot集成Swagger

配套源码地址：https://github.com/Amor128/swagger/tree/master/my-swagger-01-HelloSwagger

1.1.1 快速集成

导入依赖：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

编写配置类，启用 swagger2：

corresponding code is:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
}

访问 /swagger-ui.html资源即可访问 swagger 页面：

1.1.2 配置 swagger

配置基本信息

private ApiInfo getApiInfo() {
   Contact contact = new Contact("ermao", "http://www.sayfeng.com", "yangshifeng19@qq.com");
   return new ApiInfo("Ermao's Api Documentation",
         "This is a cool documentation",
         "1.0",
         "http://www.sayfeng.com",
         contact,
         "Apache 2.0",
         "http://www.apache.org/licenses/LICENSE-2.0",
         new ArrayList());
}

// 配置 Swagger 的 Docket 实例
@Bean
public Docket getDocket() {
   return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(getApiInfo());
}

配置完成后的效果是这样的：

配置自定义扫描接口

基于链式编程的方法给我们创造并且交由 Spring 托管的Docket对象指定要扫描的接口。

比如只想要扫描一个 package 下的接口，可以使用一下代码，注意apis方法必须夹在 select 和 build 之间。

	// 配置 Swagger 的 Docket 实例
	@Bean
	public Docket getDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(getApiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.ermao.controller"))
				.build();
	}

效果是这样的：

对于RequestHandlerSelectors，还有以下几种接口扫描的方法：

any
none
withMethodAnnotation	// 带有某种特定的基于方法的注解
withClassAnnotation		// 带有某种特定的基于类的注解
basePackage

比如为 withMethodAnnotation 传入 GetMapping.class，那么 swagger 就会扫描方法上带有 GetMapping注解的接口。举个例子，我将 swagger 这里的扫描配置成了：

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(getApiInfo())
        .select()
        .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
        .build();
}

并且将接口改成了 PostMapping：

@PostMapping("/hello")
public String hello() {
   return "Hello, Swagger!";
}

最后的结果就是 swagger 没有扫描到任何接口：

把 swagger 改成扫描 PostMapping之后的结果是这样的，如我们所预料：

除此之外，还可以使用 .paths和PathSelectors配合使用来达到通过请求路径进行过滤的效果，在这儿不做赘述：

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(getApiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.ermao.controller"))
        .paths(PathSelectors.ant("/ermao/*"))
        .build();
}

配置是否启用 swagger

只需要使用 enable 就可以使 swagger UI 不能被别人访问。

根据环境启用 swagger

思路是有很多：

先把这些 new Docket 需要的值写进 pojo 类，再加上 @ConfigurationProperties注解来注入配置类，这样就可以直接通过 yaml 控制配置的内容了！
使用 @Profile("dev")注解
使用 environment 接口方法

这里我们使用最后一种方法，首先我们再 yaml 配置文件里面配置多个环境并且启用一种：

spring:
  profiles:
    active: prod

---

spring:
  config:
    activate:
      on-profile: dev

---

spring:
  config:
    activate:
      on-profile: prod

然后将 swagger 的配置类修改成这样，注意这里的environment对象是在类里面注入的：

// 配置 Swagger 的 Docket 实例
@Bean
public Docket getDocket() {
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);
    System.out.println("================ " + flag);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(getApiInfo())
        .enable(flag)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.ermao.controller"))
        .build();
}

这样就可以根据我们在 yaml 配置文件里的配置决定是否启用 swagger 了。

API 分组

要想在这里有多个 API 分组，只需要返回多个 Docket 对象并且交由 Spring 托管就可以了。

@Bean
public Docket getDocket1() {
   Profiles profiles = Profiles.of("dev");
   boolean flag = environment.acceptsProfiles(profiles);
   System.out.println("================ " + flag);

   return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(getApiInfo())
         .groupName("ermao")
         .enable(flag)
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.ermao.controller"))
         .build();
}

@Bean
public Docket getDocket2() {
   return new Docket(DocumentationType.SWAGGER_2)
         .groupName("sanmao");
}

1.1.3 使用 swagger

使用 swagger 优点有：

在线测试
实时更新
接口分组

这里有一篇有关使用 swagger 的参考博文：https://blog.csdn.net/lw1242189467/article/details/79565075

主要就是在为我们配置的接口提供注释，比如：

Api
ApiModel
ApiOperation
……

我的配套源码中也有使用。

简而言之，swagger 是一个优秀的工具，几乎所有的大公司都在使用。

但别忘记在正式发布的时候关闭 Swagger！

码农公寓