Java中如何用Swagger生成API文档-Java-PHP中文网

Java中如何用Swagger生成API文档

尼克

发布： 2025-06-29 23:37:01

原创

1047人浏览过

如何在spring boot项目中使用swagger生成api文档？1.添加依赖，在pom.xml中引入springdoc-openapi-ui的依赖；2.创建配置类，定义openapi对象，设置标题、版本、描述等基本信息；3.在controller中使用@operation、@parameter、@apiresponse等注解描述接口信息；4.启动应用后访问http://localhost:8080/swagger-ui.html查看文档。此外，还可以使用@tag分组接口，@schema描述结构，@requestbody、@pathvariable、@requestparam分别描述不同类型的参数。通过修改配置类可自定义文档全局信息，如联系人、license等。swagger基于openapi标准生成文档，其中springdoc-openapi-ui是openapi 3.0的实现。

Java中如何用Swagger生成API文档

Swagger能帮你自动生成漂亮的API文档，省时省力，让前后端协作更顺畅。

解决方案

添加Swagger依赖

在你的pom.xml文件中添加Swagger的依赖。这里我们使用springdoc-openapi-ui，它提供了更现代的Swagger UI体验。

立即学习“Java免费学习笔记（深入）”；

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-ui</artifactId>
       <version>1.6.4</version>
   </dependency>

登录后复制

当然，你也可以选择传统的swagger2和swagger-ui，但springdoc-openapi-ui更推荐。

配置Swagger

创建一个Swagger配置类，例如SwaggerConfig.java。

   import io.swagger.v3.oas.models.OpenAPI;
   import io.swagger.v3.oas.models.info.Info;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;

   @Configuration
   public class SwaggerConfig {

       @Bean
       public OpenAPI customOpenAPI() {
           return new OpenAPI()
                   .info(new Info()
                           .title("我的API文档")
                           .version("1.0")
                           .description("这个文档包含了所有可用的API接口。"));
       }
   }

登录后复制

这个配置类定义了API文档的基本信息，比如标题、版本和描述。 @Configuration告诉Spring这是一个配置类，@Bean则告诉Spring这是一个需要被管理的Bean。

使用Swagger注解

在你的Controller类和方法上添加Swagger注解，例如@Operation、@Parameter、@ApiResponse等。

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.Parameter;
   import io.swagger.v3.oas.annotations.responses.ApiResponse;
   import org.springframework.web.bind.annotation.*;

   @RestController
   @RequestMapping("/users")
   public class UserController {

       @GetMapping("/{id}")
       @Operation(summary = "获取用户详情", description = "根据用户ID获取用户的信息。")
       @ApiResponse(responseCode = "200", description = "成功获取用户")
       @ApiResponse(responseCode = "404", description = "用户不存在")
       public String getUser(@Parameter(description = "用户ID") @PathVariable Long id) {
           // ...你的业务逻辑...
           return "用户ID: " + id;
       }

       @PostMapping
       @Operation(summary = "创建用户", description = "创建一个新的用户。")
       @ApiResponse(responseCode = "201", description = "成功创建用户")
       public String createUser(@RequestBody String user) {
           // ...你的业务逻辑...
           return "创建用户: " + user;
       }
   }

登录后复制

@Operation用于描述API接口，@Parameter用于描述参数，@ApiResponse用于描述响应。这些注解让Swagger知道如何生成文档。

访问Swagger UI

启动你的Spring Boot应用，然后在浏览器中访问http://localhost:8080/swagger-ui.html。你会看到Swagger UI界面，其中包含了所有API接口的文档。（注意，8080是你的应用端口，如果你的应用端口不是8080，请替换成你的实际端口。）

Swagger注解有哪些常用的？

Calliper 文档对比神器

文档内容对比神器

查看详情

除了上面用到的 @Operation、@Parameter、@ApiResponse，还有一些其他的Swagger注解也很有用：

@Tag: 用于给API接口分组。比如，你可以将所有用户相关的接口放在一个组里，将所有订单相关的接口放在另一个组里。
@Schema: 用于描述请求体或响应体的结构。这对于复杂的JSON对象非常有用。
@RequestBody: 用于描述请求体。它可以和@Schema一起使用，详细描述请求体的每个字段。
@PathVariable: 用于描述路径参数。和@Parameter类似，但更明确地指出参数是路径的一部分。
@RequestParam: 用于描述查询参数。和@Parameter类似，但更明确地指出参数是查询字符串的一部分。

Swagger文档如何自定义？

Swagger文档的自定义主要体现在两个方面：一是配置，二是注解。

配置方面：你可以通过修改SwaggerConfig.java来定制API文档的全局信息，比如标题、版本、描述、联系人信息、License信息等等。你还可以配置API接口的排序方式、是否显示内部接口等等。
注解方面：你可以通过使用不同的Swagger注解，详细描述API接口的各个方面。比如，你可以使用@Operation的tags属性给API接口分组，使用@Schema的example属性给请求体或响应体添加示例数据。

例如，你想给API文档添加一个联系人信息：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("我的API文档")
                        .version("1.0")
                        .description("这个文档包含了所有可用的API接口。")
                        .contact(new Contact()
                                .name("张三")
                                .email("zhangsan@example.com")
                                .url("http://example.com")));
    }
}

登录后复制

Swagger和OpenAPI有什么关系？

Swagger实际上是一套完整的API工具链，包括Swagger Editor（API设计工具）、Swagger UI（API文档展示工具）、Swagger Codegen（API代码生成工具）等等。而OpenAPI Specification（OAS）是一种用于描述RESTful API的标准格式。Swagger 2.0版本使用了Swagger Specification，而Swagger 3.0版本则改名为OpenAPI Specification。

简单来说，OpenAPI是标准，Swagger是工具，Swagger工具使用OpenAPI标准来生成API文档。所以，现在说Swagger，其实更多时候指的是OpenAPI。 springdoc-openapi-ui就是基于OpenAPI 3.0的实现。

以上就是Java中如何用Swagger生成API文档的详细内容，更多请关注php中文网其它相关文章！