SpringBoot入门，整合Swagger生成API文档

简介：Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。本文将通过一个简单的示例，将swagger整合到我们自己的springboot项目中去，生成API文档，并支持API测试。

1.pom文件引入swagger所需依赖

新建一个springboot项目，将所需的Swagger依赖引入，整个pom文件内容入下

<?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.0.RELEASE</version>
        <relativePath/>
    </parent>
    <groupId>com.swagger.demo</groupId>
    <artifactId>swagger-demo</artifactId>
    <version>1.0.0</version>
    <name>swagger-demo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <project.bulid.sourceEncoding>UTF-8</project.bulid.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- swagger依赖 -->
        <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-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>

2.swagger注解

在controller包下新建一个ApiController，随便写几个方法，并加上wagger注解，代码示例入下

package com.swagger.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@Api(value = "ApiController",tags = "api入口")
@RestController("/")
public class ApiController {

    @ApiOperation(value = "GET方法",tags = "api入口")
    @GetMapping("getMethod/{data}")
    public String getMethod(@ApiParam(value = "携带参数",required = true) @PathVariable("data") String data){
        return "这是一个GET方法"+data;
    }

    @ApiOperation(value = "POST方法",tags = "api入口")
    @PostMapping("postMethod")
    public String postMethod(){
        return "这是一个POST方法";
    }

    @ApiOperation(value = "PUT方法",tags = "api入口")
    @PutMapping("putMethod/{data}")
    public String putMethod(@ApiParam(value = "携带参数",required = true) @PathVariable("data") String data){
        return "这是一个PUT方法"+data;
    }

    @ApiOperation(value = "DELETE方法",tags = "api入口")
    @DeleteMapping("deleteMethod/{data}")
    public String deleteMethod(@ApiParam(value = "携带参数",required = true) @PathVariable("data") String data){
        return "这是一个DELETE方法"+data;
    }
}

controller的内容非常简单，本次只是一个简单的整合示例，所以其他的service啥的就懒得弄了，下面讲解下每个注解的意思。

注解名	说明	参数内容
@Api	作用于类，标识这个类是一个swagger资源	value:描述，tags:标签，相同的标签会存放到一起，以list形式呈现
@ApiOperation	标识这是一个http请求操作	value:方法描述，tags:属于哪个标签下
@ApiParam	用于方法参数	name:参数名，value:参数描述，required:是否必填

除此之外，还有一些其他的注解，如@ApiModel、@ApiModelProperty、@ApiIgnore，本文没有使用，可自行百度后尝试一下。

3.配置swagger

新建一个config包，创建一个wagger配置类，代码如下。

package com.swagger.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;

/**
 * Swagger2 配置类
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {
    @Bean
    public Docket swaggerPluginConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())                     //Api文档描述
                .select()                               //选择哪些路径和Api会生成文档
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))    //对指定路径下Api进行监控
                .paths(PathSelectors.any())             //对所有路径进行监控
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Test Demo接口文档")
                .description("API 接口文档")
                .termsOfServiceUrl("http://localhost")
                .version("1.0.0")
                .contact(new Contact("takano","","xxxxxx@qq.com"))
                .build();
    }
}

注意：一定要添加@EnableSwagger2注解

4.测试

启动项目，输入网址http://localhost:8080/swagger-ui.html，即可进入到swagger的ui界面，如下图所示

可以看到我们暴露的api接口，点击可以在线测试，我在这里测试下GET方法，点击GET方法，界面如下

点击try it out，我们设置了data为必填参数，所以这里随便填写，之后点击Execute，便可看到执行返回的结果，如下图所示。

至此，Springboot整合swagger的小示例就完成了，通过使用swagger可以帮助我们快速的生成api文档，方便调试接口，用起来很舒服。

如有错误，欢迎批评指正，我会及时修改。