SpringBoot结合Swagger生成接口文档

大家好，我是猿猴小冷，今天给大家分享一下SpringBoot结合Swagger2生成接口文档

前言

由于我们在写程序中我们的接口API众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，抱怨声不绝于耳。
随着时间推移，之后不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。为了解决上面这样的问题，我在这将介绍接口 API的重磅好伙伴Swagger2

---

提示：以下是本篇文章正文内容，下面案例可供参考

一、Swagger2是什么？

编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的API接口文档，间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

二、使用步骤

1.引入 Swagger2库

代码如下（swagger2依赖包）：

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

2.创建Swagger2的配置类

代码如下：

package com.lq.x_admin.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
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;

/**
 * Swagger2 配置类
 * @Configuration 让 Spring 容器加载该配置类
 * @EnableSwagger2 用于启动 swagger2
 */
@EnableSwagger2
@Component
@Configuration
public class Swagger2Config {
    /**
     * swagger2 启动后，通过createRestApi函数创建Docket的Bean，
     * apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
     * select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lq.x_admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建API接口文档")
                .description("springbootAPI接口文档")
                .termsOfServiceUrl("http://localhost:8080/")
                .version("1.0")
                .build();
    }
}

3.使用注解描述你的API接口

package com.lq.x_admin.controller;

import com.lq.x_admin.entity.User;
import com.lq.x_admin.service.UserService;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import javax.servlet.http.HttpSession;

@RestController
@Api(value = "获取用户数据",tags = "用户登录处理")
public class UserController {
    @Resource
    private UserService userService;

    @PostMapping("/user/doLogin")
    @ApiOperation("用户登录的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名"),
            @ApiImplicitParam(name = "password",value = "密码")
    })
    public String doLogin(@RequestParam("username") String username, @RequestParam("password") String password, HttpSession session) throws Exception {
        User user=userService.login(username,password);
        if (user!=null){
            session.setAttribute("loginUser",user);
            return "index";
        }else{
            return "login";
        }
    }
}

4.注解说明

@Configuration 让 Spring 容器加载该配置类

@EnableSwagger2 用于启动 swagger2

@Api 描述接口类

@ApiOperation注解来给接口API增加说明

@ApiImplicitParams注解给多个参数增加说明

@ApiImplicitParam注解给单个参数增加说明
	1. name：参数名
	2. value：参数说明
	3. dataType：参数类型，默认String，其他值dataType=“Integer”
	4. paramType：参数发在哪个地方
	5. header：请求参数的获取 @RequestHeader
	6. query：请求参数的获取 @RequestParam
	7. path：请求参数的获取 @PathVariable
	8. body（不常用）
	9. form （不常用）
	10.required：是否必须填写
	11. defaultValue：默认值

@ApiModel 描述实体类

@ApiModel 注解给属性增加说明

5.效果展示

a. 启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，就能看到浏览器所展示的RESTful API的页面。我们可以再点开具体的API请求，以POST类型的登录请求处理为例，可找到接口中我们配置的一些接口的描述信息以及参数的描述信息

b. 接口测试功能

总结

Swagger2可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大API接口文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个API接口。

今天我的分享到此结束，我是猿猴小冷，谢谢大家！