springboot集成swagger

目录

swagger介绍

添加swagger依赖

配置swagger2

访问swagger

浏览swagger文档

自定义swagger文档信息

swagger介绍

Swagger是一种用于构建、文档化和测试RESTful Web服务的开源工具集。它包括一组规范和工具，可以帮助开发者设计、构建和维护API（应用程序编程接口）。Swagger的主要目标是简化API开发过程，使API文档易于理解和使用。

以下是Swagger的一些关键特点和组件：

1. API文档自动生成：Swagger可以从API代码中自动生成文档。它支持多种编程语言和框架，包括Java、C#、Python等。这些文档可以包括有关API端点、请求参数、响应数据等详细信息。

2. 互动API测试：Swagger UI是Swagger的一个组件，它提供了一个用户友好的界面，允许开发者在不离开文档页面的情况下测试API端点。这有助于快速验证API的行为和功能。

3. 标准化API规范：Swagger使用OpenAPI规范（以前称为Swagger规范）来描述API。这个规范定义了API的结构，包括路径、HTTP方法、参数、响应等，从而提供了一种标准化的方式来描述API。

4. 代码生成：Swagger可以根据API规范生成客户端和服务端代码，从而帮助开发者快速构建与API交互的应用程序。

5. 生态系统：Swagger有一个庞大的生态系统，包括许多第三方工具和插件，可以扩展其功能。这些工具可以用于自定义文档生成、安全性检查、性能监视等。

6. 支持多种格式：Swagger支持多种数据格式，包括JSON和YAML，以描述API规范和文档。

总之，Swagger是一种有助于简化API开发和文档化过程的工具，它可以提高API的可理解性、可测试性和互操作性。这对于团队合作、客户与供应商之间的沟通以及API的广泛采用都非常有价值。

添加swagger依赖

在本章pig会将swagger与spring boot2集成。前置条件是：

创建maven项目，spring boot相关依赖导入完成， 引入maven依赖。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version> <!-- 使用最新版本 -->
</dependency>

配置swagger2

配置Swagger2：创建一个配置类，用于配置Swagger2。在这个类上使用@EnableSwagger2注解启用Swagger2，并配置Swagger的一些属性。以下是一个示例配置类：

1. 请确保将your.package.name替换为你的Controller类所在的包路径。

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
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("your.package.name")) // 指定扫描的Controller包
            .paths(PathSelectors.any())
            .build();
    }
}

访问swagger

运行应用程序：现在，你的Spring Boot应用程序已经配置好了Swagger2。启动应用程序，然后访问Swagger UI，通常在以下URL上：

http://localhost:8080/swagger-ui.html

如果你的应用程序不是在默认端口8080上运行，应该将端口号替换为你的应用程序的端口号。

浏览swagger文档

Swagger UI将显示你的API文档，你可以在那里浏览并测试API端点。

这些步骤涵盖了如何将Swagger2集成到Spring Boot 2.x应用程序中。一旦集成完成，你可以使用Swagger来生成、文档化和测试你的API。确保在生产环境中禁用Swagger，以防止未经授权的访问。

自定义swagger文档信息

1. 自定义API信息：

   • 在Swagger规范文件中，可以指定API的标题、描述、版本、作者等信息。这些信息将出现在Swagger UI中。

2. 自定义路径和操作：

   • 为每个API路径自定义描述和摘要信息，以便用户更好地理解API的用途。
   • 为每个操作自定义描述、摘要、参数说明等信息。

3. 参数自定义：

   • 指定每个API操作所需的参数，并提供参数的描述、类型、格式等信息。
   • 使用x-*扩展字段可以添加自定义信息，例如x-example来提供示例值。

则我们可以自己去定义ApiInfo, 返回自定义的apiInfo放到接口文档里。

    private ApiInfo apiInfo(){
        Contact contact = new Contact("大力pig的博客","https://blog.csdn.net/m0_53753920?spm=1011.2266.3001.5343", "");
        return new ApiInfo(
                "大力pig的swagger文档",
                "在小的帆船也能远航",
                "1.0",
                "https://blog.csdn.net/m0_53753920?spm=1011.2266.3001.5343",
                contact,
                "",
                "",
                new ArrayList<>()
        );
    }

自定义的apiInfo放到Docket对象的apiinfo信息里，如果我们想要多个组，可以创建多个docket对象。 

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jin.controllder")) // 指定扫描的Controller包
                .paths(PathSelectors.any())
                .build();
    }