【云原生】springboot 集成swagger,实现接口的生成，并生成接口文档

精选原创

jiao_zg22 2024-04-15 19:09:23 博主文章分类：架构专题 ©著作权

文章标签 springboot swagger springfox 文章分类 架构后端开发

©著作权归作者所有：来自51CTO博客作者jiao_zg22的原创作品，谢绝转载，否则将追究法律责任

要在Spring Boot项目中集成Swagger以自动生成接口文档，请按照以下步骤操作：

步骤 1：添加Swagger依赖

在Spring Boot项目的pom.xml文件中添加Swagger的依赖。自Swagger 3.0以来，它被称为SpringFox，因此确保使用最新的依赖。下面是使用SpringFox的例子：

<!-- SpringFox Boot Starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

步骤 2：配置Swagger

创建一个新的Java配置类来启用Swagger。以下是SpringFox 3.0.0的配置样例：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.basePackage("com.example.yourapp"))              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

在.apis(RequestHandlerSelectors.basePackage("com.example.yourapp"))中，替换com.example.yourapp为你的项目基础包名。

步骤 3：启用Swagger UI

无需额外配置。通过添加了SpringFox的依赖和上述配置，Swagger UI将自动启用。

步骤 4：编写你的控制器

确保你的控制器和REST端点使用了Swagger的注解，如@ApiOperation。这不是必需的，因为Swagger会自动为你的所有端点生成文档，但是添加这些注解可以提供更多的信息和自定义。

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class YourController {

    @ApiOperation(value = "Get example", notes = "This endpoint is an example for Swagger documentation")
    @GetMapping("/example")
    public String getExample() {
        return "Hello, Swagger!";
    }
}