笔记大全

使用spring boot怎么实现对Swagger2进行整合

更新时间：2024-01-01

第一段：添加Swagger2依赖

在使用Spring Boot框架时，我们可以通过添加Swagger2依赖，来对Swagger2进行整合。在pom.xml文件中添加以下依赖：


    <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>

添加完依赖后，我们需要在我们的Spring Boot项目中启用Swagger2。在Spring Boot主应用程序类上，添加注解 @EnableSwagger2，如下所示：


    @SpringBootApplication
    @EnableSwagger2
    public class DemoApplication {
        //...
    }

第二段：配置Swagger2的信息

在启用Swagger2后，我们需要配置它的一些信息，比如文档的标题、描述、版本号等。我们需要在项目中创建一个Swagger2配置类，并在配置类中添加配置信息。如下所示：


    @Configuration
    public class SwaggerConfig {
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(apiInfo());
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("更多Spring Boot相关文章请关注：http://www.example.com/")
                    .termsOfServiceUrl("http://www.example.com/")
                    .contact("xurunyun")
                    .version("1.0")
                    .build();
        }
    }

在上面的代码中，我们创建了一个 Docket 对象，并指定了基本的前缀包名，然后设置路径和API构建的详细信息。我们使用 apiInfo() 方法创建一个 ApiInfo 实例，它包含API文档的信息。

第三段：使用Swagger2注解

当我们配置Swagger2的信息后，我们需要使用Swagger2的注解来描述我们的RESTful API接口。以下是常用的Swagger2注解：

@Api - 用于注解Controller
@ApiOperation - 用于注解类中的方法，表示方法的作用
@ApiParam - 用于注解方法中的参数，描述参数的含义
@ApiResponse - 描述接口返回信息的状态以及原因

使用Swagger2注解时，我们需要在Spring Boot主应用程序类上添加注解 @ComponentScan(basePackages = {"com.example.demo"})，并创建一个Controller，如下所示：


    @RestController
    @RequestMapping("/api")
    @Api(tags = "用户相关接口", description = "用户相关接口")
    public class UserController {
    
        @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
        @GetMapping("/users")
        public List<User> getUsers() {
            return new ArrayList<>();
        }
    
        @ApiOperation(value = "创建用户", notes = "创建用户")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String", paramType = "query"),
                @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "int", paramType = "query")
        })
        @PostMapping("/users")
        public User createUser(String name, int age) {
            return new User();
        }
    }

在上面的代码中，我们使用了 @Api 注解来注解Controller，使用 @ApiOperation 注解来注解类中的方法及其作用，使用 @ApiImplicitParam 注解来注解方法中的参数及其含义。

第四段：访问Swagger2 UI

当我们配置完Swagger2的信息后，我们可以访问Swagger2 UI界面。我们可以在浏览器中输入 http://localhost:8080/swagger-ui.html，即可访问Swagger2 UI页面：


<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
    <style>
        html {
          box-sizing: border-box;
          overflow: -moz-scrollbars-vertical;
          overflow-y: scroll;
        }
        *, *:before, *:after {
          box-sizing: inherit;
        }
        body {
          margin:0;
          background: #fafafa;
        }
    </style>
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="./swagger-ui-bundle.js"></script>
    <script src="./swagger-ui-standalone-preset.js"></script>
    <script>
        window.onload = function() {
            // Begin Swagger UI call region
            const ui = SwaggerUIBundle({
                url: "/v2/api-docs",
                dom_id: '#swagger-ui',
                deepLinking: true,
                presets: [
                    SwaggerUIBundle.presets.apis,
                    SwaggerUIStandalonePreset
                ],
                plugins: [
                    SwaggerUIBundle.plugins.DownloadUrl
                ],
                layout: "BaseLayout"
            })
            // End Swagger UI call region
            window.ui = ui
        }
    </script>
</body>
</html>

在Swagger2 UI页面中，我们可以看到我们运行时生成的API文档，可以方便的测试我们的RESTful API接口，测试界面如下图所示：

c语言编程笔录