Swagger的概念与应用

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它遵循 OpenAPI 规范，这是 Linux 基金会的一个项目，旨在通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程。

Swagger的作用

Swagger 的主要作用可以概括为以下几点：

• 将项目中所有的接口展现在页面上，使后端程序员无需编写专门的接口文档给前端使用者。
• 接口更新后，只需修改代码中的 Swagger 描述即可实时生成新的接口文档，避免了接口文档过时的问题。
• 通过 Swagger 页面，可以直接进行接口调用和测试，降低了项目开发阶段的调试成本。

Swagger的版本

Swagger目前有多个版本，其中 Swagger 2.X 版本和少量的 1.X 版本是市面上的主流。Swagger 3.0 发布于 2020 年 7 月，虽然是最新版，但许多项目仍在使用旧版本。新版本相较于旧版本，配置更为简单，例如依赖项配置减少了 50%，并且新版 Swagger 页面设计风格现代化，更具科技感，整体美观了不少。值得一提的是，Swagger 的升级过程非常平滑，从老版本升级到新版本，只需要简单的配置即可，用于描述接口的注解还是延续了老版本的用法，这样就可以在不修改大部分主要代码的情况下，成功升级到最新版本。

Swagger的使用

在 Spring Boot 项目中集成 Swagger 通常需要以下步骤：

1. 添加 Swagger 相关依赖到项目中。
2. 在 Spring Boot 的启动类或配置类中添加  @EnableSwagger2 注解，开启 Swagger 功能。
3. 配置 Swagger 文档摘要信息，如扫描路径、API 信息等。
4. 通过访问 http://localhost:8080/swagger-ui.html 来查看和使用 Swagger UI。

Swagger的注解

Swagger 提供了一系列注解来描述和控制 API 文档的生成，例如：

• @Api：用于类，标记该类是 Swagger 资源。
• @ApiOperation：用于方法，描述一个 HTTP 请求的操作。
• @ApiModel 和  @ApiModelProperty：用于模型和属性，描述实体和属性的信息。
• @ApiImplicitParam 和  @ApiImplicitParams：用于方法，描述方法的参数。
• @ApiResponse 和  @ApiResponses：用于方法，描述方法的响应信息。
• @ApiIgnore：用于类或方法，表示不在 Swagger UI 中显示。

总结

Swagger 是一个强大的工具，它不仅能够实时更新 API 文档，还能在线测试 API，极大地提高了开发效率。在正式发布时，可以关闭 Swagger，出于安全考虑，同时也节省内存。通过 Swagger，开发人员可以更好地理解和使用 API，从而提高前后端的协作效率。

例子

下面是一段Swagger的代码案例

@Configuration

public class SwaggerConfiguration {
	@Bean
	public GroupedOpenApi createRestApi() {
		return GroupedOpenApi.builder()
				.group("接口文档")
				.packagesToScan("com.yami.shop.api").build();
	}
	@Bean
	public OpenAPI springShopOpenApi() {
		return new OpenAPI()
				.info(new Info().title("Mall4j接口文档")
						.description("Mall4j接口文档，openapi3.0 接口，用于前端对接")
						.version("v0.0.1")
						.license(new License().name("使用请遵守AGPL3.0授权协议").url("https://www.mall4j.com")));
	}

}

1. @Configuration 注解

<JAVA>
@Configuration
public class SwaggerConfiguration {}

• @Configuration 表示这是一个 Spring 配置类，Spring 会在启动时加载这个类，并将其中的 @Bean 方法注册为 Spring 容器中的 Bean。

---

2. @Bean 方法：createRestApi()

<JAVA>
@Bean
public GroupedOpenApi createRestApi() {    
    return GroupedOpenApi.builder()            
                         .group("接口文档")            
                         .packagesToScan("com.yami.shop.api")
                         .build();
}

• 这个方法定义了一个 GroupedOpenApi Bean，用于配置接口文档的分组和扫描路径。
• group("接口文档")：将生成的接口文档分组，命名为“接口文档”。
• packagesToScan("com.yami.shop.api")：指定扫描的包路径为 com.yami.shop.api，Swagger 会扫描该包下的所有 Controller 类，并生成对应的接口文档。

---

3. @Bean 方法：springShopOpenApi()

<JAVA>
@Bean
public OpenAPI springShopOpenApi() {    
    return new OpenAPI().info(new Info()
                        .title("Mall4j接口文档")                    
                        .description("Mall4j接口文档，openapi3.0 接口，用于前端对接")                           .version("v0.0.1")                    
                        .license(new License()
                        .name("使用请遵守AGPL3.0授权协议")
                        .url("https://www.mall4j.com")));}

• 这个方法定义了一个 OpenAPI Bean，用于配置接口文档的全局信息。
• title("Mall4j接口文档")：设置文档的标题为“Mall4j接口文档”。
• description("Mall4j接口文档，openapi3.0 接口，用于前端对接")：设置文档的描述信息。
• version("v0.0.1")：设置文档的版本号。
• license(new License().name("使用请遵守AGPL3.0授权协议").url("https://www.mall4j.com"))：设置文档的许可证信息，包括名称和链接。

---

4. 整体作用

这段代码的作用是：

1. 配置 Swagger 的分组和扫描路径，将 com.yami.shop.api 包下的接口生成文档，并分组为“接口文档”。
2. 定义接口文档的全局信息，包括标题、描述、版本号和许可证信息。

---

5. 运行效果

启动 Spring Boot 应用后，访问 Swagger 的 UI 界面（通常是 http://localhost:8080/swagger-ui.html），你会看到：

• 文档的标题为“Mall4j接口文档”。
• 文档的描述为“Mall4j接口文档，openapi3.0 接口，用于前端对接”。
• 文档的版本号为 v0.0.1。
• 文档的许可证信息为“使用请遵守AGPL3.0授权协议”，并附带链接。
• 所有 com.yami.shop.api 包下的接口会被扫描并展示在“接口文档”分组中。

---

6. 依赖说明

要使用这段代码，需要在 pom.xml 中添加以下依赖（如果使用 Maven）：

<XML>
<dependency>    
    <groupId>org.springdoc</groupId>    
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>    <version>2.0.0</version>
</dependency>

• springdoc-openapi-starter-webmvc-ui 是 Spring Boot 中用于支持 OpenAPI 3.0 的依赖。