Spring Boot中Swagger API文档优化

发布时间：2024-11-15 13:50:05 作者：小樊
来源：亿速云阅读：93

在Spring Boot项目中，Swagger是一个非常有用的工具，可以帮助我们自动生成API文档。为了优化Swagger API文档，我们可以从以下几个方面进行操作：

集成Swagger：

在Spring Boot项目中，我们可以通过添加依赖来集成Swagger。在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>

配置Swagger：

创建一个Swagger配置类，例如SwaggerConfig.java，并添加以下代码：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
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();
    }
}

这里，我们使用@EnableSwagger2注解启用Swagger2，并使用Docket类创建一个API文档实例。我们通过RequestHandlerSelectors和PathSelectors来选择需要生成文档的Controller和路径。

优化API文档：

为了优化API文档，我们可以采取以下措施：

为Controller和API方法添加详细的注释，包括请求参数、响应结果、错误码等信息。
使用@ApiOperation、@ApiParam等注解来描述API的功能和参数。
自定义Swagger UI页面，例如添加全局参数、响应示例等。

生成API文档：

在项目根目录下创建一个名为swagger-ui.html的文件，并添加以下代码：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="/webjars/springfox-swagger-ui/swagger-ui.css" >
    <link rel="icon" type="image/png" href="/webjars/springfox-swagger-ui/favicon-32x32.png" sizes="32x32" />
    <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="/webjars/springfox-swagger-ui/swagger-ui-bundle.js"> </script>
<script src="/webjars/springfox-swagger-ui/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: "StandaloneLayout"
        });

        // End Swagger UI call region
        window.ui = ui;
    };
</script>
</body>
</html>

这里，我们通过修改url属性来指定Swagger API文档的地址。默认情况下，该地址为/v2/api-docs，对应于我们在Swagger配置类中定义的Docket实例。

现在，启动Spring Boot项目后，访问http://localhost:8080/swagger-ui.html，即可查看生成的API文档。

Spring Boot中Swagger API文档优化

相关阅读