SpringCloud技术集成Swagger

swager2.0

集成：

1. 添加依赖

首先，在需要集成Swagger的微服务项目的pom.xml中添加Swagger相关的依赖。你可以参考以下依赖配置（注意，版本号可能会随着时间推移而更新，请根据实际情况选择最新的稳定版本）：

<properties>  
    <springfox.version>3.x.x</springfox.version> <!-- 请替换为最新版本号 -->  
</properties>  
  
<dependencies>  
    <dependency>  
        <groupId>io.springfox</groupId>  
        <artifactId>springfox-boot-starter</artifactId>  
        <version>${springfox.version}</version>  
    </dependency>  
    <!-- 如果你还需要Swagger UI，可以添加以下依赖 -->  
    <dependency>  
        <groupId>io.springfox</groupId>  
        <artifactId>springfox-swagger-ui</artifactId>  
        <version>${springfox.version}</version>  
    </dependency>  
</dependencies>

2. 创建Swagger配置类 

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;  
import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.Configuration;  
  
@Configuration  
@EnableSwagger2  
public class SwaggerConfig {  
  
    @Bean  
    public Docket api() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .select()  
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage")) // 替换为你的Controller所在包路径  
                .paths(PathSelectors.any())  
                .build();  
    }  
}

3. 在Controller上使用Swagger注解

在Controller类和方法上使用Swagger的注解，如@Api、@ApiOperation等，以提供API的元数据信息。

import io.swagger.annotations.Api;  
import io.swagger.annotations.ApiOperation;  
import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RestController;  
  
@RestController  
@Api(tags = "用户管理相关接口")  
public class UserController {  
  
    @GetMapping("/users")  
    @ApiOperation("获取用户列表")  
    public List<User> getUserList() {  
        // ...  
    }  
}

4. 访问Swagger UI

启动你的微服务后，可以通过访问http://<你的服务地址>/swagger-ui.html来查看Swagger UI界面，并浏览和管理API文档。

swager3.0

集成：

1. 添加Swagger 3.0依赖

在pom.xml文件中添加Swagger 3.0的相关依赖。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version> <!-- 使用适合你项目的版本 -->
</dependency>

2. 配置Swagger 3.0

在Spring Boot应用程序中创建一个配置类来配置Swagger 3.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.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean  
    public Docket api() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .select()  
                .apis(RequestHandlerSelectors.basePackage("com.yourcompany.yourproject.controllers")) // 替换为你的Controller所在包路径  
                .paths(PathSelectors.any())  
                .build();  
    }  
  
    private ApiInfo apiInfo() {  //这个方法也可以不要
        return new ApiInfoBuilder()  
                .title("Your API Docs") // API文档的标题  
                .description("Your API description") // API文档的描述  
                .version("1.0") // API的版本  
                .build();  
    } 
}

3. 使用Swagger注解

import io.swagger.annotations.Api;  
import io.swagger.annotations.ApiOperation;  
import org.springframework.web.bind.annotation.GetMapping;  
import org.springframework.web.bind.annotation.RestController;  
  
@RestController  
@Api(tags = "User Controller") // 控制器描述  
public class UserController {  
  
    @GetMapping("/users")  
    @ApiOperation("Get user list") // 方法描述  
    public List<User> getUserList() {  
        // ...  
    }  
}

4. 访问Swagger UI

启动Spring Boot应用程序后，可以通过访问http://localhost:8080/swagger-ui/index.html（端口号可能根据应用配置有所不同）来查看和测试API。

Swagger 2.0的技术思想

Swagger 2.0的技术思想主要是提供一个统一的、标准化的方式来描述、生成和测试RESTful Web服务。它通过定义一套规范，允许开发人员使用YAML、JSON或注解的方式来描述API的接口、参数、请求和响应等信息。Swagger 2.0的核心目标是简化API的开发过程，提高API的可见性和可维护性。

具体实现上，Swagger 2.0提供了以下功能：

1. API描述：通过Swagger规范，开发人员可以详细地描述API的各个方面，包括路径、方法、参数、响应等。
2. 自动生成文档：基于Swagger规范的描述，Swagger 2.0可以自动生成API的文档，并提供友好的UI界面供开发人员查看和测试。
3. 在线测试：Swagger UI不仅展示了API的文档，还提供了在线测试的功能，允许开发人员直接发送请求并查看响应结果。

Swagger 3.0（OpenAPI 3.0）的技术思想

Swagger 3.0进一步扩展和强化了API描述、生成和测试的能力，其技术思想主要体现在以下几个方面：

1. 标准化与跨平台：OpenAPI 3.0是一个更加标准化、跨平台、跨语言的API描述规范。它使用YAML或JSON格式的Schema文件来描述API的结构和功能，使得API的描述更加统一和易于管理。
2. 增强的扩展性：OpenAPI 3.0支持更多的扩展功能，如回调、链式操作、组件重用等。这使得API的描述更加灵活和强大，能够支持更复杂的业务场景。
3. 安全性增强：OpenAPI 3.0提供了更多的安全功能，如基本身份验证、OAuth2等。这些功能可以帮助开发人员更好地保护API的安全性，防止未经授权的访问和数据泄露。

进步点

1. 标准化：OpenAPI 3.0进一步推动了API描述的标准化进程，使得API的描述更加统一和易于管理。
2. 扩展性：相比Swagger 2.0，OpenAPI 3.0提供了更多的扩展功能，支持更复杂的业务场景和更灵活的开发方式。
3. 安全性：OpenAPI 3.0在安全性方面有了显著的提升，提供了更多的安全功能和机制来保护API的安全性。
4. 社区支持：随着OpenAPI 3.0的推广和应用，越来越多的开发者和组织开始支持和采用它。这使得OpenAPI 3.0具有更广泛的社区支持和更丰富的资源。

综上所述，Swagger 2.0和3.0（OpenAPI 3.0）在API描述、生成和测试方面都有着重要的技术思想和应用价值。随着技术的不断发展和完善，OpenAPI 3.0相比Swagger 2.0在标准化、扩展性、安全性和社区支持等方面都取得了显著的进步。

总结：

Swagger3.0比Swagger2.0更安全更复杂，如果有的选优先使用Swagger3.0。目前主要用于api文档的展示和api接口的测试，也可以方便前后端进行接口的联调。