Spring Boot从入门到精通（十一）集成Swagger框架，实现自动生成接口文档

2022-03-10 00:20:42

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 是一组开源项目，其中主要要项目如下：

Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验

Swagger 1.2文档转换成Swagger 2.0文档等功能。

Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。

Swagger-js: 用于JavaScript的Swagger实现。

Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

在项目开发中，Swagger 可以根据不同的业务代码实现自动生成API文档，提供给前端调用方在线测试，且自动显示返回采纳数JSON格式的字符串，从而节省后端与前端人员的沟通与调试成本。

Swagger 有一个最大的劣势就是“侵入性”模式，配置信息必须在具体代码中来实现，在下面的搭建过程中，大家就会明白说的是什么意思了。

新建Maven项目，在pom.xml文件引入依赖

方式一：使用官方推荐依赖，在pom.xml文件中添加Swagger包依赖，具体配置信息如下：

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-parent</artifactId>

        <version>2.2.5.RELEASE</version>

        <relativePath/> <!-- lookup parent from repository -->

    </parent>

    <groupId>com.example</groupId>

    <artifactId>springboot-study-demo07</artifactId>

    <version>0.0.1-SNAPSHOT</version>

    <packaging>jar</packaging>

    <name>springboot-study-demo07</name>

    <description>Demo project for Spring Boot</description>

    <properties>

        <java.version>1.8</java.version>

    </properties>

    <dependencies>

        <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>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-web</artifactId>

        </dependency>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-test</artifactId>

            <scope>test</scope>

            <exclusions>

                <exclusion>

                    <groupId>org.junit.vintage</groupId>

                    <artifactId>junit-vintage-engine</artifactId>

                </exclusion>

            </exclusions>

        </dependency>

    </dependencies>

    <build>

        <plugins>

            <plugin>

                <groupId>org.springframework.boot</groupId>

                <artifactId>spring-boot-maven-plugin</artifactId>

            </plugin>

        </plugins>

    </build>

</project>

方式二：使用第三方包引入依赖，在pom.xml文件中添加第三方swagger包依赖，具体配置信息如下：

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent>

        <groupId>org.springframework.boot</groupId>

        <artifactId>spring-boot-starter-parent</artifactId>

        <version>2.2.5.RELEASE</version>

        <relativePath/> <!-- lookup parent from repository -->

    </parent>

    <groupId>com.example</groupId>

    <artifactId>springboot-study-demo07</artifactId>

    <version>0.0.1-SNAPSHOT</version>

    <packaging>jar</packaging>

    <name>springboot-study-demo07</name>

    <description>Demo project for Spring Boot</description>

    <properties>

        <java.version>1.8</java.version>

    </properties>

    <dependencies>

        <dependency>

            <groupId>com.spring4all</groupId>

            <artifactId>swagger-spring-boot-starter</artifactId>

            <version>1.9.1.RELEASE</version>

        </dependency>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-web</artifactId>

        </dependency>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-test</artifactId>

            <scope>test</scope>

            <exclusions>

                <exclusion>

                    <groupId>org.junit.vintage</groupId>

                    <artifactId>junit-vintage-engine</artifactId>

                </exclusion>

            </exclusions>

        </dependency>

    </dependencies>

    <build>

        <plugins>

            <plugin>

                <groupId>org.springframework.boot</groupId>

                <artifactId>spring-boot-maven-plugin</artifactId>

            </plugin>

        </plugins>

    </build>

</project>

自定义Swagger配置信息

新建Swagger配置类，需要注意的是“Swagger scan base package”，这是扫描注解的配置，即API接口位置，对前端调用方提供服务接口的位置。

package com.yoodb.study.demo07.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.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder().title("API接口文档")

                .description("“Java精选”微信公众号信息")

                .version("1.0.0")

                .build();

    }

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.yoodb.study.demo07")) //API接口所在的包位置

                .paths(PathSelectors.any())

                .build();

    }

}

新建Controller类文件

新建HelloWorldController类文件，创建GET和POST两种请求方法，以接口方式提供给前端调用，具体代码如下：

package com.yoodb.study.demo07;

import io.swagger.annotations.*;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.PostMapping;

import org.springframework.web.bind.annotation.RestController;

@Api(value = "hello")

@RestController

public class HelloWorldController {

    /**

     * 根据公众号名称获取详细描述信息

     * @return

     */

    @ApiOperation(value = "获取公众号详细描述信息", notes = "根据公众号名称获取详细描述信息")

    @ApiImplicitParam(name = "name", value = "公众号名称", required = true, dataType = "String", paramType = "path")

    @ApiResponses(value = {

            @ApiResponse(code = 200, message = "Successful — 请求已完成"),

            @ApiResponse(code = 400, message = "请求语法问题或无法满足请求"),

            @ApiResponse(code = 401, message = "Unauthorized，未授权访问"),

            @ApiResponse(code = 404, message = "服务器找不到资源；文件不存在"),

            @ApiResponse(code = 500, message = "服务器不能完成请求")}

    )

    @GetMapping("getName/{name}")

    public String getName(@PathVariable(value = "name") String name) {

        return "关注微信公众号“" +name+ "”(w_z90110)，" +

                "Spring Boot系列文章持续更新中，" +

                "带你从入门到精通，玩转Spring Boot框架。";

    }

    /**

     * 根据公众号编号获取详细描述信息

     * @return

     */

    @ApiOperation(value = "获取公众号详细描述信息", notes = "根据公众号编号获取详细描述信息")

    @ApiImplicitParam(name = "id", value = "公众号编号", required = true, dataType = "String", paramType = "path")

    @ApiResponses(value = {

            @ApiResponse(code = 200, message = "Successful — 请求已完成"),

            @ApiResponse(code = 400, message = "请求语法问题或无法满足请求"),

            @ApiResponse(code = 401, message = "Unauthorized，未授权访问"),

            @ApiResponse(code = 404, message = "服务器找不到资源；文件不存在"),

            @ApiResponse(code = 500, message = "服务器不能完成请求")}

    )

    @PostMapping("getId/{id}")

    public String getId(@PathVariable(value = "id") String id) {

        return "关注微信公众号“Java精选”(" +id+ ")，" +

                "Spring Boot系列文章持续更新中，" +

                "带你从入门到精通，玩转Spring Boot框架。";

    }

}

设置访问API文档

在application.yml配置文件中，增加配置信息如下：

springfox.documentation.swagger.v2.path: /api-docs

此配置信息是指以json串的形式访问request mapping，可以自定义，防止与自身代码冲突，使用位置参考截图所示（项目启动后通过地址访问该服务）：

添加启动类文件

新建启动类文件，使用@EnableSwagger2注解，具体代码如下：

package com.yoodb.study.demo07;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication

@EnableSwagger2

public class SpringbootStudyDemo07Application {

    public static void main(String[] args) {

        SpringApplication.run(SpringbootStudyDemo07Application.class, args);

    }

}

完成上述代码配置后，启动Spring Boot程序，访问swagger地址：

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

Swagger常用注解

@Api：用在类上，说明该类的作用。以标记一个Controller类做为swagger文档资源，如果目前在找工作或者以后要跳槽考虑，可以搜索微信小程序“Java精选面试题”，内涵3000道初中高级面试题以及几千到选择题，选择题内涵答案解析，使用方式参考如下：

@Api(value = "hello")

@ApiOperation：用在方法上，说明方法的作用，Url资源的定义，使用方式参考如下：

@ApiOperation(value = "获取公众号详细描述信息", notes = "根据公众号名称获取详细描述信息")

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。使用方式参考如下：

@ApiImplicitParam(name = "name", value = "公众号名称", required = true, dataType = "String", paramType = "path")

name：参数名

dataType：参数类型

required：参数是否必须传

value：说明参数的意思

defaultValue：参数的默认值

paramType：表示参数放在什么位置

paramType参数值包含如下：

header->请求参数的获取：@RequestHeader(代码中接收注解)

query->请求参数的获取：@RequestParam(代码中接收注解)

path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)

body->请求参数的获取：@RequestBody(代码中接收注解)

form->（不常用）

@ApiResponses：用于方法上，表示一组响应。

@ApiResponse：在@ApiResponses注解内，一般用于表达一个错误的响应信息，使用方式参考如下：

@ApiResponses(value = {

            @ApiResponse(code = 200, message = "Successful — 请求已完成"),

            @ApiResponse(code = 400, message = "请求语法问题或无法满足请求"),

            @ApiResponse(code = 401, message = "Unauthorized，未授权访问"),

            @ApiResponse(code = 404, message = "服务器找不到资源；文件不存在"),

            @ApiResponse(code = 500, message = "服务器不能完成请求")}

    )

code->数字，提示状态码400

message->信息

response->抛出异常的类

@ApiModel：用于类，描述一个Model的信息，一般用在请求参数无法使用，表示对类进行说明，用于参数用实体类接收。

@ApiModelProperty：用于方法，描述一个model的属性，表示对model属性的说明或者数据操作更改。

本文篇文章的项目源码（springboot-study-demo07）地址：

https://github.com/yoodb/springboot

码农公寓

相关文章