正文 

当前位置： 首页 > java > java框架

springboot2系列教程|集成swagger2构建强大的restfulapi文档

一个优秀的废人      2022-05-18     523

关键词：

技术图片

前言

快过年了，不知道你们啥时候放年假，忙不忙。反正我是挺闲的，所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么使用 Swagger2 ？

相信刚开始不熟悉 web 开发的时候，大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点：

  1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
  2. 接口返回结果不明确。
  3. 不能直接在线测试接口，通常需要使用工具，比如 postman。
  4. 接口文档太多，不好管理。

这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能：

  1. 文档自动更新，只要生成 Api 的网址没变，基本不需要跟前端沟通。
  2. 接口返回结果非常明确，包括数据类型，状态码，错误信息等。
  3. 可以直接在线测试文档，而且还有实例提供给你。
  4. 只需要一次配置便可使用，之后只要会有一份接口文档，非常易于管理。

集成演示

首先新建一个 SpringBoot 项目，还不会的参考我这篇旧文—— 如何使用 IDEA 构建 Spring Boot 工程

构建时，在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾，因为我这里用于操作实际的数据库，所以我勾选了。

生成 SpringBoot 后的 Pom 文件依赖如下：这里使用的是 2.4.0 的 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 http://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.1.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.nasus</groupId>
    <artifactId>swagger2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger2</name>
    <description>Demo project for Swagger2</description>

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

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

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

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
    </dependencies>

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

</project>

第二步，在 SpringBoot 启动类（Application）的同级目录新建一个 Swagger 配置类，注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录，否则生成 Api 文档失败，代码如下：

package com.nasus;

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;

/**
 * Project Name:swagger2-demo <br/>
 * Package Name:com.nasus <br/>
 * Date:2019/1/22 22:52 <br/>
 * <b>Description:</b> TODO: 描述该类的作用 <br/>
 *
 * @author <a href="turodog@foxmail.com">nasus</a><br/>
 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@Configuration
// 启用 Swagger2
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 文档信息对象
                .apiInfo(apiInfo())
                .select()
                // 被注解的包路径
                .apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 标题
                .title("springboot 利用 swagger 构建 API 文档")
                // Api 文档描述
                .description("简单优雅的 restful 风格，https://blog.csdn.net/turodog/")

                .termsOfServiceUrl("https://blog.csdn.net/turodog/")
                // 文档作者信息
                .contact(new Contact("陈志远", "https://github.com/turoDog", "turodog@foxmail.com"))
                // 文档版本
                .version("1.0")
                .build();
    }
}

第三步，配置被注解的 Controller 类，编写各个接口的请求参数，返回结果，接口描述等等，代码如下：

package com.nasus.controller;

import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
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.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

/**
 * Project Name:swagger2-demo <br/>
 * Package Name:com.nasus.controller <br/>
 * Date:2019/1/22 22:07 <br/>
 * <b>Description:</b> TODO: 描述该类的作用 <br/>
 *
 * @author <a href="turodog@foxmail.com">nasus</a><br/>
 * Copyright Notice =========================================================
 * This file contains proprietary information of Eastcom Technologies Co. Ltd.
 * Copying or reproduction without prior written approval is prohibited.
 * Copyright (c) 2019 =======================================================
 */
@RestController
@RequestMapping("/student")
// @Api：修饰整个类，描述Controller的作用
@Api("StudentController Api 接口文档")
public class StudentController {

    @Autowired
    private StudentService studentService;

    // @ApiOperation：描述一个类的一个方法，或者说一个接口
    @ApiOperation(value="获取所有学生列表", notes="获取所有学生列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<Student> getStudent() {
        List<Student> list = studentService.findAll();
        return list;
    }

    @ApiOperation(value="添加学生信息", notes="添加学生信息")
    // @ApiImplicitParam：一个请求参数
    @ApiImplicitParam(name = "student", value = "学生信息详细实体", required = true, dataType = "Student")
    @PostMapping("/save")
    public Student save(@RequestBody Student student){
        return studentService.save(student);
    }

    @ApiOperation(value="获学生信息", notes="根据url的id来获取学生详细信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
    @GetMapping("/{id}")
    public Student findById(@PathVariable("id") Integer id){
        return studentService.findById(id);
    }

    @ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生")
    @ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path")
    @DeleteMapping("/{id}")
    public String deleteById(@PathVariable("id") Integer id){
        studentService.delete(id);
        return "success";
    }

    @ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息")
    // @ApiImplicitParams：多个请求参数
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"),
            @ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student")
    })
    @PutMapping(value="/{id}")
    public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
        Student oldStudent = this.findById(id);
        oldStudent.setId(student.getId());
        oldStudent.setName(student.getName());
        oldStudent.setAge(student.getAge());
        studentService.save(oldStudent);
        return "success";
    }

    // 使用该注解忽略这个API
    @ApiIgnore
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

第四步，启动项目，访问 http://localhost:8080/swagger-ui.html 地址，结果如下图：

技术图片

项目源代码

github

图解接口

技术图片

技术图片

技术图片

Swagger2 常用注解简介

@ApiOperation：用在方法上，说明方法的作用
  1.value: 表示接口名称
  2.notes: 表示接口详细描述 
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  1.paramType：参数位置
  2.header 对应注解：@RequestHeader
  3.query 对应注解：@RequestParam
  4.path  对应注解: @PathVariable
  5.body 对应注解: @RequestBody
  6.name：参数名
  7.dataType：参数类型
  8.required：参数是否必须传
  9.value：参数的描述
  10.defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  1.code：状态码
  2.message：返回自定义信息
  3.response：抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
@Api：修饰整个类，描述Controller的作用
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

注意事项

@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。

后语

如果看到这里，说明你喜欢这篇文章，请转发、点赞。微信搜索「一个优秀的废人」，关注后回复「1024」送你一套完整的 java 教程。

技术图片

springboot2,gradle集成swagger2

gradle文件增加//swaggerimplementation"io.springfox:springfox-swagger2:2.9.2"implementation"io.springfox:springfox-swagger-ui:2.9.2"　　添加配置类SwaggerConfigpackagecom.zuo.model.config;importorg.springframework 查看详情

springboot2.x系列教程（七十）springbootactuator集成及自定义endpoint详解

前言曾经看到SpringBootActuator这个框架时，一直在想，它到底有什么作用呢？虽然知道它提供了很多端点，有助于应用程序的监控和管理，但如果没有直接的实践案例，还是很难有说服力的。直到上篇文章《微服务架构：Nacos本地... 查看详情

springboot2.x系列教程（七十一）springbootactuator，每一个端点都有案例

前言在微服务系统架构中，服务的监控是必不可少的。目前大多数微服务应用又是基于SpringCloud系列，也可以说是基于SpringBoot系列的。此时使用SpringBootActuator来进行微服务的监控，不仅功能全面，而且非常方便。在上篇文章《Spr... 查看详情

springboot2.x系列教程（七十一）springbootactuator，每一个端点都有案例

前言在微服务系统架构中，服务的监控是必不可少的。目前大多数微服务应用又是基于SpringCloud系列，也可以说是基于SpringBoot系列的。此时使用SpringBootActuator来进行微服务的监控，不仅功能全面，而且非常方便。在上篇文章《Spr... 查看详情

springboot2集成swagger3.0使用了拦截器出现报错endofthestreamoradocumentseparatorisexpected(代码片段)

swagger版本:3.0.0依赖:<dependency> <groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency>报错界面:我 查看详情

springboot2.x版本配置swagger2

参考技术A为什么要引入Swagger?有过后台开发和前端联调的人都会被接口文档折磨，更新不及时，文档和代码不一致，无法调试，swagger就是为了解决这个问题。看下swagger官方介绍Swagger是一个规范和完整的框架，用于生成、描述、... 查看详情

springboot系列五：集成swagger文档

本篇开始介绍Api文档Swagger的集成一、引入maven依赖<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency& 查看详情

springboot集成swagger2生成api接口文档(代码片段)

SpringBoot2.3.0集成Swagger2引入Swagger2相应的依赖入门示例SpringBoot2集成Swagger2后启动报错结语背景：最近在工作中发现，已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是因为开发人员在... 查看详情

springboot2.x集成knife4j(代码片段)

...。如何使用knife4j?简略的说一下，基础环境搭建可参考：SpringBoot2.x集成Swagger2这里我说一下主要配置区别：环境说明：新增knife4j.version：2.0.21.导入pom依赖<dependency& 查看详情

mp实战系列之集成swagger(代码片段)

其实与spring+springmvc+mybatis集成swagger没什么区别，只是之前写的太不好了，所以这次决定详细写。提到swagger不得不提rest,rest是一种架构风格，里面有对不同的资源有不同的请求标识。例如PUT,POST,GET,DELETE，OPTIONS,HEAD,PATCH等。对于技... 查看详情

springboot2集成api文档工具swagger-ui(下)(代码片段)

接上篇swaggerUI提供了可视化界面帮助我们管理服务的访问路口，这就需要我们在代码中规范我们的书写格式。并且在swagger的界面上还能够模拟浏览器对服务进行访问。接口总览创建POST接口创建一个保存用户的接口@RequestMapping(val... 查看详情

springboot系列十springboot集成swaggerui

一、Swagger介绍Swagger能成为最受欢迎的RESTAPIs文档生成工具之一，有以下几个原因：Swagger可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。Swagger可以生成客户端SDK代码用于各种不同的平台上的实现。Swagge... 查看详情

解决springboot2.6和swagger冲突的问题(代码片段)

...台服务从SpringBoot1升级到2版本，主要目的是为了使用SpringBoot2的实时监控功能。集成的时候无法启动，根据日志判断与swagger有关。信息如下：org.springframework.context.ApplicationContextException:Failedtostartbean'documentationP 查看详情

springboot2.0图文教程|集成邮件发送功能

...springboot/spring-boots-send-mail大家好，后续会间断地奉上一些SpringBoot2.x相关的博文，包括SpringBoot2.x教程和SpringBoot2.x新特性教程相关，如WebFlux等。还有自定义Starter组件的进阶教程，比如：如何封装一个自定义图 查看详情

解决springboot2.6和swagger冲突的四种方法(代码片段)

...台服务从SpringBoot1升级到2版本，主要目的是为了使用SpringBoot2的实时监控功能。集成的时候无法启动，根据日志判断与swagger有关。信息如下：org.springframework.context.ApplicationContextException:Failedtostartbean'documentationP 查看详情

springboot集成swagger2生成api接口文档(代码片段)

SpringBoot2.3.0集成Swagger2引入Swagger2相应的依赖入门示例SpringBoot2集成Swagger2后启动报错结语背景：最近在工作中发现，已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是因为开发人员在... 查看详情

springboot2系列教程|整合thymeleaf

前言如题，今天介绍Thymeleaf，并整合Thymeleaf开发一个简陋版的学生信息管理系统。SpringBoot提供了大量模板引擎，包含Freemarker、Groovy、Thymeleaf、Velocity以及Mustache，SpringBoot中推荐使用Thymeleaf作为模板引擎，因为Thymeleaf提供了完美... 查看详情

springboot2系列教程|配置日志

前言如题，今天介绍springboot默认日志的配置。默认日志Logback默认情况下，SpringBoot用Logback来记录日志，并用INFO级别输出到控制台。如果你在平常项目中用过SpringBoot，你应该已经注意到很多INFO级别的日志了。默认日志长这样：20... 查看详情