Swagger集成

发布时间：2023-05-17

Swagger 集成详解

Swagger 是一款用于构建、描述、调用和可视化 RESTful API 的开源工具。它可以根据代码自动生成 API 文档，方便开发人员进行接口文档的编写和测试。本文将从多个方面对 Swagger 集成进行详细的阐述。

一、Swagger 简介

Swagger 是由 Tony Tam 在 2011 年创建的一个开源项目。它旨在简化 RESTful API 的开发和文档生成，并且可以通过自动生成的 API 文档来提高沟通效率。Swagger 可以支持多种编程语言和框架。 通常情况下，RESTful API 的开发涉及到以下方面：

  • 定义资源
  • 定义 HTTP 方法
  • 定义认证
  • 定义错误响应
  • 编写业务逻辑代码
  • 编写测试代码
  • 编写文档 这些工作很繁琐，而 Swagger 可以根据代码自动生成 API 文档，从而省去了很多手动编写文档的时间和精力。

二、Swagger 集成

Swagger 的集成非常简单，只需要在项目中加入 Swagger 的相关依赖即可。

1、Maven 集成

使用 Maven 构建项目时，在 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>

同时，在启动类中加入注解 @EnableSwagger2 即可启用 Swagger。

package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

启动应用，访问 http://localhost:8080/swagger-ui.html 即可看到 Swagger 自动化生成的 API 文档。

2、Spring Boot 集成

在 Spring Boot 中集成 Swagger 更加方便，只需要加入以下 Maven 依赖即可：

<dependency>
    <groupId>springfox.documentation</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>springfox.documentation</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

然后在 Application 启动类中加入注解 @EnableSwagger2 即可启用 Swagger。

package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

启动应用后，访问 http://localhost:8080/swagger-ui.html 即可查看生成的 API 文档。

三、配置与使用

Swagger 集成之后，我们需要对其进行配置和使用。

1、配置

Swagger 配置很灵活，可以进行各种自定义设置。 我们可以通过在配置类中加入 Bean 对象来配置一些 Swagger 的默认信息。

package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
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()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Demo API")
                .description("Demo API Doc")
                .version("1.0")
                .contact(new Contact("Swagger", "https://swagger.io", ""))
                .build();
    }
}

在这个配置文件中，我们通过 Docket 类进行了各种设置，包括扫描控制器包、显示文档的路径、设置 API 相关信息等。可以看到其中设置了 API 的标题、描述、版本、联系信息等。通过 @Bean 注解将这个 Docket 对象放入 Spring 容器中，就能够自动生效。

2、使用

Swagger 使用非常简单，只需要在控制器上加入一些注解即可。 首先，我们需要在控制器类上加入 @Api 注解，标识这是一个 API 控制器，同时可以设置一些额外信息。

package com.example.demo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(value = "DemoController", tags = {"Demo"})
@RequestMapping("/demo")
public class DemoController {
    @ApiOperation(value = "Hello World API", notes = "返回 Hello World")
    @GetMapping("/hello")
    public String hello() {
        return "Hello World!";
    }
}

在 hello 方法上加入 @ApiOperation 注解，即可设置其请求方法、接口描述、接口参数、返回值等信息。其中 value 表示接口的名称，notes 表示接口的描述。 这样，Swagger 就会自动通过扫描控制器类和注解信息来绘制出可视化的 API 文档。

四、结语

本文对 Swagger 集成进行了详细的阐述，包括 Swagger 的简介、集成、配置和使用。Swagger 作为一款非常好用的工具，在 RESTful API 的开发和文档编写时有着很大的作用和价值。

推荐文章