SpringBoot2 | 第十七篇：集成Swagger2在线调试（官方版）

Swagger

​ 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

​ 前端和后端 唯一联系，变成了 API 接口；API文档 自然就成了前后端开发人员联系的纽带，变得尤为的重要，swagger就是一款让你更好的书写API文档的框架。

​ Swagger 是一款自动生成 在线文档 + 接口调试 的工具。在 WEB 开发中不可否认的是我们需要给客户端提供 API 接口，这个时候需要借助 postman、rap 等工具 进行调试，以便于接口能正常交付给客户端人员，用过其它工具的应该知道一个 POST 请求一堆参数是非常枯燥且烦人的事情，而 Swagger 就是让你摆脱这种束缚感….

swagger 优缺点

• 集成方便，功能强大
• 在线调试与文档生成
• 代码耦合，需要注解支持，但不影响程序性能

环境/版本一览：

• 开发工具：Intellij IDEA 2018.2.2
• springboot： 2.0.5.RELEASE
• jdk：1.8.0_171
• maven：3.3.9
• springfox-swagger2：2.8.0
• springfox-swagger-ui：2.8.0

1、pom.xml

swagger 需要的依赖有两个：springfox-swagger2 和 springfox-swagger-ui，版本要求一致

<dependencies>
    <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>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
    <!--  swagger2 begin   -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>
    <!--  swagger2 end   -->
</dependencies>

2、config

@EnableSwagger2 开启 swagger2

package com.fatal.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 配置类
 * @author: Fatal
 * @date: 2018/10/17 0017 14:54
 */
@Configuration
@EnableSwagger2 // 开启swagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.fatal.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("标题：用户信息管理系统-接口文档")
                .description("描述：about xxx")
                .contact(new Contact("fatal", "fatal's url", "fatal's email"))
                .version("1.0")
                .build();
    }

}

3、entity

​ swagger 提供了非常齐全的注解，为POJO提供了@ApiModel、@ApiModelProperty，以便更好的渲染最终结果

package com.fatal.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;

/**
 * User 实体
 * @author: Fatal
 * @date: 2018/10/17 0017 15:05
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel
@Accessors(chain = true)
public class User {

    private Long id;
    @ApiModelProperty(name = "username", value = "用户名")
    private String username;
    @ApiModelProperty(name = "password", value = "密码")
    private String password;

}

4、controller

package com.fatal.controller;

import com.fatal.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import java.util.Arrays;
import java.util.List;

/**
 * User 控制器
 * @author: Fatal
 * @date: 2018/10/17 0017 15:07
 */
@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/")
    @ApiOperation(value = "查询所有", notes = "获取用户列表")
    public List<User> get() {
        List<User> users = Arrays.asList(new User(0L, "米彩", "123"),
                new User(1L, "米琪", "123"));
        return users;
    }

    @PostMapping("/")
    @ApiOperation(value = "添加用户", notes = "添加用户操作")
    public User insert(User user) {
        return user;
    }

    @PutMapping("/")
    @ApiOperation(value = "更新用户", notes = "更新用户操作")
    public User update(@ApiParam(name = "id", value = "用户主键")
                       @RequestParam(name = "id") Long id) {
        return new User()
                .setId(id)
                .setUsername("fatal")
                .setPassword("123456");
    }

}

5、显示

启动工程，打开浏览器输入 http://localhost:8080/swagger-ui.html 即可

注意

swagger 没有做安全方面的防护，可能需要我们自己做相关的工作。

6、笔记

注解描述

• @Api： 描述Controller
• @ApiIgnore： 忽略该Controller，指不对当前类做扫描
• @ApiOperation： 描述Controller类中的method接口
• @ApiParam： 描述单个入参信息，与@ApiImplicitParam不同的是，他是写在参数左侧的。如（@ApiParam(name = “username”,value = “用户名”) String username）
• @ApiModel： 描述POJO对象
• @ApiModelProperty： 描述POJO对象中的属性值
• @ApiImplicitParam： 描述单个入参信息，如果请求参数在url上，@ApiImplicitParam 上加paramType = “path”
• @ApiImplicitParams： 描述多个入参信息
• @ApiResponse： 描述单个出参信息
• @ApiResponses： 描述多个出参信息
• @ApiError： 接口错误所返回的信息

当我们指定了 Swagger 的扫描路径后，很多注解我们不写，它会取参数信息为默认值。

参考资料

SpringBoot非官方教程 | 第十一篇：springboot集成swagger2，构建优雅的Restful API

一起来学SpringBoot | 第十一篇：集成Swagger在线调试

总结

SpringBoot的知识已经有前辈在我们之前探索了。比较喜欢的博主有：唐亚峰 | Battcn、方志朋的专栏、程序猿DD、纯洁的微笑。对这门技术感兴趣的可以去他们的博客逛逛。谢谢他们的分享~~

以上文章是我用来学习的Demo，都是基于 SpringBoot2.x 版本。

源码地址: https://github.com/ynfatal/springboot2-learning/tree/master/chapter17_1

学习 唐亚峰 、方志朋 前辈的经验