Spring Boot + Swagger2

素颜马尾好姑娘i 2023-10-01 17:46 28阅读 0赞

在这篇文章中，我们配置了一个 Spring Boot 应用程序来集成 swagger2。[春季启动示例][Link 1]我们已经公开了一个 REST API。我们开发的此类 REST 服务的文档非常重要。该文档应帮助服务的消费者了解哪些所有服务可用、签名、预期输入。还应该有一些简单的方法来测试服务是否启动。暴露的服务必然会发生变化，因此同时也需要更新文档。如果这是手动完成的，那么这将是一个非常乏味的过程，尤其是随着 REST 服务数量的增加。这就是招摇的地方。它有助于自动化此文档过程。此外，API 中的每个更改都应同时在参考文档中进行描述。手动完成这项工作是一项乏味的工作，因此该过程的自动化是不可避免的。在下一篇文章中，我们将看看[各种可用的 Swagger 注释及其用途。][Swagger] 在另一篇文章中，我们研究了[将 Swagger 与 Spring Boot Profile 结合使用][Swagger _ Spring Boot Profile]。  
这种格式以前称为 Swagger 规范，已捐赠给 Linux 基金会协作项目 Open API Initiative（或 OAI）。我们[在另一篇文章中使用 OpenAPI3 实现了 Swagger][OpenAPI3 _ Swagger]。

Spring Boot Swagger- 目录

**[Spring Boot + Swagger 示例 Hello World 示例][Spring Boot _ Swagger _ Hello World]** [Spring Boot + Swagger - 了解各种 Swagger 注释][Swagger] [Spring Boot + Swagger + Profile - 为 Swagger 应用程序实现 Spring Boot Profile ][Swagger _ Spring Boot Profile] [Spring Boot + Swagger 3 (OpenAPI 3) Hello World 示例][OpenAPI3 _ Swagger] [Spring Boot + Swagger 3 (OpenAPI 3) + 安全示例][Spring Boot _ Swagger 3 _OpenAPI 3_ _]

## 什么是招摇 ##

Swagger 被广泛用于 API 的可视化，并通过 Swagger UI 为前端开发人员提供在线沙箱。对于本教程，我们将使用 Swagger 2 规范的 Springfox 实现。Swagger 是一种工具、规范和完整的框架实现，用于生成 RESTful Web 服务的可视化表示。它使文档能够以与服务器相同的速度更新。当通过 Swagger 正确定义时，消费者可以用最少的实现逻辑来理解远程服务并与之交互。因此，Swagger 消除了调用服务时的猜测。

视频

本教程在下面的 Youtube 视频中进行了解释。

让我们开始-

该项目将如下 - 在 Maven 中，我们需要 swagger 依赖项。Maven 将如下 -

![b2de94b815d01ce578619885dc8cb9d1.png][]

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    	<modelVersion>4.0.0</modelVersion>
    	<groupId>com.javainuse</groupId>
    	<artifactId>springboot-swagger-test</artifactId>
    	<version>0.0.1-SNAPSHOT</version>
    	<packaging>jar</packaging>
    	<parent>
    		<groupId>org.springframework.boot</groupId>
    		<artifactId>spring-boot-starter-parent</artifactId>
    		<version>1.4.1.RELEASE</version>
    	</parent>
    
    	<dependencies>
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-web</artifactId>
    		</dependency>
    		
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>2.4.0</version>
    		</dependency>
    
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>2.4.0</version>
    		</dependency>
    		
    	</dependencies>
    
    	<build>
    		<plugins>
    			<plugin>
    				<groupId>org.springframework.boot</groupId>
    				<artifactId>spring-boot-maven-plugin</artifactId>
    			</plugin>
    		</plugins>
    	</build>
    </project>

Note- Previously was using 2.2.2 version for springfox-swagger2 maven dependencies. But this
    version has issues. If overloaded methods are used for exposing REST API it will not work properly. Only for one of the overloaded methods the 
    swagger documentation can be seen and not for the other.

如下创建 Application.java -

package com.javainuse.swaggertest;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class Application {
    
    	public static void main(String[] args) {
    		SpringApplication.run(Application.class, args);
    	}
    }

@RequestMapping 将 /api/javainuse 请求映射到 sayHello() 方法。

package com.javainuse.swaggertest;
    
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    public class HelloController {
    	
    	@RequestMapping(method = RequestMethod.GET, value = "/api/javainuse")
    	public String sayHello() {
    		return "Swagger Hello World";
    	}
    }

要启用 Swagger 2，我们使用注解 @EnableSwagger2。  
定义了一个 Docket bean，并使用它的 select() 方法获得了 ApiSelectorBuilder 的一个实例。ApiSelectorBuilder 我们配置了 Swagger 暴露的端点。  
在定义了 Docket bean 之后，它的 select() 方法会返回一个 ApiSelectorBuilder 的实例，该实例提供了一种控制 Swagger 暴露的端点的方法。  
使用 RequestHandlerSelectors 和 PathSelectors 我们配置谓词以选择 RequestHandlers。

package com.javainuse.swaggertest;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    
    import com.google.common.base.Predicate;
    
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    import static springfox.documentation.builders.PathSelectors.regex;
    import static com.google.common.base.Predicates.or;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
    	@Bean
    	public Docket postsApi() {
    		return new Docket(DocumentationType.SWAGGER_2).groupName("public-api")
    				.apiInfo(apiInfo()).select().paths(postPaths()).build();
    	}
    
    	private Predicate<String> postPaths() {
    		return or(regex("/api/posts.*"), regex("/api/javainuse.*"));
    	}
    
    	private ApiInfo apiInfo() {
    		return new ApiInfoBuilder().title("JavaInUse API")
    				.description("JavaInUse API reference for developers")
    				.termsOfServiceUrl("http://javainuse.com")
    				.contact("javainuse@gmail.com").license("JavaInUse License")
    				.licenseUrl("javainuse@gmail.com").version("1.0").build();
    	}
    
    }

这些是唯一需要的更改。现在转到**http://localhost:8080/swagger-ui.html**。  
我们将看到公开 API 的文档如下 - 使用 Try it 按钮，我们还可以检查服务是否已启动。 在下一篇文章中，我们将通过示例看到各种[swagger 注释的使用][Swagger]

![a818dd8b223535e44179a1ee2916f838.png][]

### 下载源代码 ###

下载它 -  
[Spring Boot + Swagger][Spring Boot _ Swagger]

[Link 1]: https://www.javainuse.com/spring/SpringBoot_HelloWorld
[Swagger]: https://www.javainuse.com/spring/boot_swagger_annotations
[Swagger _ Spring Boot Profile]: https://www.javainuse.com/spring/boot_swagger_profile
[OpenAPI3 _ Swagger]: https://www.javainuse.com/spring/boot_swagger3
[Spring Boot _ Swagger _ Hello World]: https://www.javainuse.com/spring/boot_swagger
[Spring Boot _ Swagger 3 _OpenAPI 3_ _]: https://www.javainuse.com/spring/boot_swaggersec
[b2de94b815d01ce578619885dc8cb9d1.png]: https://img-blog.csdnimg.cn/img_convert/b2de94b815d01ce578619885dc8cb9d1.png
[a818dd8b223535e44179a1ee2916f838.png]: https://img-blog.csdnimg.cn/img_convert/a818dd8b223535e44179a1ee2916f838.png
[Spring Boot _ Swagger]: https://www.javainuse.com/zip/spring/boot/springboot-swagger-test.rar