前后端交互神器 —— Swagger2

前后端交互神器 —— Swagger2

目录

前言

相信不少个人和公司已经使用前后端分离开发或者正在走向前后端分离的路上。
前后端分离中，后端工作人员最头疼的问题就是写各种API文档给前端，还有就是写注释（自己不想写注释，看别人代码时会抱怨没有注释）。
但是一个工具让我们在开发中将二者合为一体成为可能。
就是我们今天要介绍的神器——Swagger2。
它不仅能让注释和接口“合体”，并且能让注释本身成为一种艺术。
废话不多说，我们进入正题。

SpringBoot与Swagger2的整合

首先我们打开IDEA（也可以是Eclipse），用Spring Initializer创建我们的演示项目
springboot-swagger
以下是创建项目步骤（IDEA）



勾选我们所需的模块


最后点finish完成我们项目的创建

我们首先在创建项目的pom文件中添加swagger2的坐标（依赖）

<?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/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.laoqin</groupId>
    <artifactId>springboot-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-swagger</name>
    <description>Demo project for Swagger</description>

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

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </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>
        <!--swagger界面-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

然后在src>java>com.laoqin.springboot.swagger.config包下创建我们的配置类

package com.laoqin.springboot.swagger.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 SwaggerConfiguration {
    @Bean
    public Docket restApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.laoqin.springboot.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("我的Swagger项目")
                .description("这里是项目的一些介绍")
                .termsOfServiceUrl("https://blog.csdn.net/itkfdektxa")
                .version("1.0")
                .build();
    }
}

最后我们在controller包下写几个请求并通过注解加上注释

package com.laoqin.springboot.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Description
 * @Author QinLing
 * @Date 2019/10/24 14:42
 **/
@Slf4j
@RestController("/user")
@Api("用户相关")
public class UserController {

    @ApiOperation("查询用户-根据id")
    @GetMapping("/{id}/get")
    public String getUserById(@PathVariable Integer id){
        return "xxx";
    }

    @ApiOperation("删除用户-根据id")
    @DeleteMapping("/{id}/delete")
    public String deleteUserById(@PathVariable Integer id){
        return "xxx";
    }
}

运行我们的SpringBoot项目，然后访问以下地址

swagger-ui地址

得到了我们的API接口说明文档

以上就是我们整合的基本操作，接下来就可以把地址愉快的扔给前台了。
因为我们接口注释一般只到方法级别，如果想要更详细的生成文档，可以继续阅读第三个主题。

Swagger2 注解大全

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

以上就是整个Swagger2的基础内容。