第九章 SpringBoot系列整合swagger3 api接口文档

系列文章目录

第一章 SpringBoot系列之从0搭建项目
第二章 SpringBoot系列返回json数据
第三章 SpringBoot系列GlobalException全局异常捕获
第四章 SpringBoot系列整合Mybatis做增删改查
第五章 SpringBoot系列配置JPA访问数据
第六章 SpringBoot系列使用JdbcTemplate操作数据
第七章 SpringBoot系列静态资源处理，访问磁盘文件
第八章 SpringBoot系列实现任务调度Scheduled

---

文章目录

• 系列文章目录
• 前言
• 一、swagger3注解使用介绍
• 二、代码整合demo
• • 1.pom.xml引入依赖
  • 2.接口代码中加入swagger注解
  • 3.增加swagger配置类
  • 4.设置排除拦截路径
• 二、API可视化界面效果
• 总结

---

前言

日常开发过程中接口文档是必不可少得一项工作，由于接口增加、变更使得文档变得难以维护，也容易忘记或漏掉接口，说实话大部分开发者也不太愿意去维护这么个文档，还有就是接口测试角度分析，通常我们开发完一个接口需要使用接口调用工具postman等等http调用工具来做接口的测试，swagger的出现简直就是我们开发者的福音，swagger可自动为我们生成接口文档页面，可在页面直接查看接口入参、出参以及做接口测试，话不多说接下来我们就来看看SpringBoot项目是如何接入swagger api文档神器的。

---

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

一、swagger3注解使用介绍

@Api 写在controller类上，入参API接口名称/介绍
@ApiOperation 用在接口方法上，入参接口名称/介绍
@ApiModel 用在数据实体类上，入参实体类名称/介绍
@ApiModelProperty 用在对象数据实体属性上，入参属性名称/介绍
@ApiParam 单个请求参数说明
@ApiImplicitParams 接口参数说明
@ApiResponses 接口响应提示(比如400参数不对等等注释)
@ApiIgnore 忽略接口方法

二、代码整合demo

1.pom.xml引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.接口代码中加入swagger注解

①controller类

package com.example.demo.controller;

import com.example.demo.dao.JdbcPersonDao;
import com.example.demo.dto.JsonDataDTO;
import com.example.demo.model.PersonDO;
import com.example.demo.service.PersonService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;


@Api("swagger3演示controller")
@RestController
@RequestMapping("/")
public class DemoController {

    @Autowired
    private PersonService personService;

    @Autowired
    private JdbcPersonDao jdbcPersonDao;

    @ApiOperation("test接口")
    @PostMapping("/test")
    public String test(@RequestBody PersonDO personDO) {
        return "实体类入参demo";
    }

    @ApiOperation("test接口")
    @GetMapping("/test")
    public String test() {
        return "Hello World";
    }

    @ApiOperation("getJsonData接口")
    @GetMapping("/getJsonData")
    public JsonDataDTO getJsonData() {
        JsonDataDTO jsonDataDTO = new JsonDataDTO();
        jsonDataDTO.setName("张三");
        jsonDataDTO.setAge(18);
        jsonDataDTO.setSex("男");
        return jsonDataDTO;
    }

    @ApiOperation("globalExceptionTest接口")
    @GetMapping("/globalExceptionTest")
    public void globalExceptionTest() throws Exception {
        throw new Exception("发生异常啦！！！");
    }

    @ApiOperation("selectPersonInfo接口")
    @GetMapping("/selectPersonInfo")
    public PersonDO selectPersonInfo(@RequestParam("id") @ApiParam("主键ID") Long id) {
        return personService.selectPersonInfo(id);
    }

    @ApiOperation("selectPersonInfoJpaDemo接口")
    @GetMapping("/selectPersonInfoJpaDemo")
    public PersonDO selectPersonInfoJApademo(@RequestParam("id") @ApiParam("主键ID") Long id) {
        return jdbcPersonDao.getPersonDO(id);
    }

    @ApiOperation("queryDataForJdbc接口")
    @GetMapping("/queryDataForJdbc")
    public PersonDO queryDataForJdbc(@RequestParam("id") @ApiParam("主键ID") Long id) {
        return personService.selectPersonInfoJpaDemo(id);
    }

}

②接口参数对象DTO

package com.example.demo.dto;

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

@ApiModel("swagger接口对象实体类")
@Data
public class JsonDataDTO {

    /**
     * 姓名
     */
    @ApiModelProperty("姓名")
    private String name;

    /**
     * 年龄
     */
    @ApiModelProperty("年龄")
    private Integer age;

    /**
     * 性别
     */
    @ApiModelProperty("性别")
    private String sex;
}

3.增加swagger配置类

package com.example.demo.config;

import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.HashSet;

@EnableOpenApi
@Configuration
public class SwaggerConfiguration {

    @Value("server.port")
    private String port;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")

                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(true)

                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())

                // 接口调试地址
                .host("http://localhost:"+port)

                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(getProtocols("https", "http"));
    }

    private HashSet<String> getProtocols(String https, String http) {
        HashSet set = new HashSet<String>();
        set.add(https);
        set.add(http);
        return set;
    }

    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Demo Api Doc")
                .description("rest接口文档 lc")
                .version("v1.0")
                .build();
    }
}

4.设置排除拦截路径

比如项目中登录拦截器，安全框架拦截等等，需要排除swagger路径不然可能会被拦截导致访问不了swagger界面。

/swagger**/**
/webjars/**
/v3/**
/doc.html

二、API可视化界面效果

POST请求接口，点右上角Try it out 可编辑入参并Execute做接口测试，往下就是响应信息，从图片我们可以看到代码中注释说明/名称。


GET请求接口，点右上角Try it out 可编辑入参并Execute做接口测试，往下就是响应信息，从图片我们可以看到代码中注释说明/名称。

---

总结

有到了总结时刻了，一句话：简直太好用啦！快点把它引入到你们项目当中，减少工作量！！！