Springboot 整合 Swagger2

最新推荐文章于 2023-04-20 16:00:03 发布

敲代码的大雄

最新推荐文章于 2023-04-20 16:00:03 发布

阅读量165

点赞数 1

分类专栏：学习笔记文章标签： java spring boot swagger2

本文链接：https://blog.csdn.net/qq_34217386/article/details/116780790

版权

学习笔记专栏收录该内容

26 篇文章 0 订阅

订阅专栏

Springboot 整合 Swagger2

现如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，

但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger2 就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

项目整合后目录结构

在这里插入图片描述

pom.xml 依赖

<?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.1.7.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-test</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>11</java.version>
    </properties>

    <dependencies>
        <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>
        <!-- 引入 Druid 数据源依赖：https://mvnrepository.com/artifact/com.alibaba/druid -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid</artifactId>
            <version>1.1.9</version>
        </dependency>
        <!-- mybatis-plus依赖-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>3.3.2</version>
        </dependency>
        <!-- mybatis-plus 代码生成器-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-generator</artifactId>
            <version>3.3.2</version>
        </dependency>
        <!-- 代码生成模板-->
        <dependency>
            <groupId>org.freemarker</groupId>
            <artifactId>freemarker</artifactId>
            <version>2.3.30</version>
        </dependency>
        <!-- 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>
        <!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.16</version>
            <scope>provided</scope>
        </dependency>

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

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

</project>

SwaggerConfig

package com.example.demo.common.config;


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

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docker(){
        // 构造函数传入初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
                .apiInfo(apiInfo())
                //分组名称
                .groupName("test1")
                //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
                .enable(true)
                .select()
                //apis： 指定哪些接口暴露给swagger
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.module"))
                //paths： 这里是控制哪些路径的api会被显示出来，比如下方的参数就是除了/user以外的其它路径都会生成api文档
                .paths((String a) ->!a.equals("/user"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("名字：name", "个人链接：http://xxx.xxx.com/", "邮箱：XXX");
        return new ApiInfo(
                "标题内容", // 标题
                "描述内容", // 描述
                "版本内容：v1.0", // 版本
                "链接：http://baidu.com/", // 组织链接
                contact, // 联系人信息
                "许可：Apach 2.0 ", // 许可
                "许可链接：XXX", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

如需设置多个分组，可添加多个Docket Bean，如：
在这里插入图片描述
swagger 整合完毕。

测试

接下来我们启动项目，访问 http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了
在这里插入图片描述
添加接口

controller

package com.example.demo.module.emp.controller;


import com.example.demo.common.dto.R;
import com.example.demo.module.emp.entity.Emp;
import com.example.demo.module.emp.service.IEmpService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

import java.util.List;

/**
 * <p>
 *  前端控制器
 * </p>
 *
 * @author xx
 * @since 2021-05-14
 */
@RestController
@RequestMapping("/emp")
@Api(tags = "用户管理类")
public class EmpController {

    @Autowired
    private IEmpService iEmpService;

    @ApiOperation(value = "用户信息接口")
    @GetMapping(value = "/data")
    public List<Emp> all(){
        return iEmpService.list();
    }

    @ApiOperation(value = "根据id获取用户信息接口")
    @ApiImplicitParam(value = "用户id",name = "id")
    @GetMapping(value = "/{id}")
    public R getById(@PathVariable(value = "id")Integer id){
        return R.ok(iEmpService.getById(id));
    }

}

实体类添加 swagger 注解

package com.example.demo.module.emp.entity;

import com.baomidou.mybatisplus.annotation.TableName;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import java.io.Serializable;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * <p>
 * 
 * </p>
 *
 * @author xx
 * @since 2021-05-14
 */
@Data
@EqualsAndHashCode(callSuper = false)
@TableName("tbl_emp")
@ApiModel(value="Emp对象", description="")
public class Emp implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "用户id")
    @TableId(value = "emp_id", type = IdType.AUTO)
    private Integer empId;

    @ApiModelProperty(value = "用户名称")
    private String empName;

    @ApiModelProperty(value = "性别 1：男 2：女")
    private String gender;

    @ApiModelProperty(value = "邮箱")
    private String email;

    @ApiModelProperty(value = "单位id")
    private Integer dId;
}

这里涉及到多个 swagger 注解，贴上 swagger 注解说明：

用于controller类上：
@Api – 对请求类的说明

用于方法上面（说明参数的含义）：
@ApiOperation – 方法的说明
@ApiImplicitParams、@ApiImplicitParam – 方法的参数的说明
@ApiImplicitParams – 用于指定多个参数的说明

用于方法上面（返回参数或对象的说明）：
@ApiResponses、@ApiResponse – 方法返回值的说明
@ApiResponses – 用于指定多个参数的说明

用于对象类：
@ApiModel – 用在 JavaBean 类上，说明 JavaBean 的用途
@ApiModelProperty – 用在 JavaBean 类的属性上面，说明此属性的的含议

添加完接口，刷新下刚才的页面，可以看到如下效果
在这里插入图片描述
可以看到刚添加的接口都列出来了，包括接口请求方式，接口地址以及接口的名字等。

点开接口，可以看到接口的参数、参数要求、响应数据结构等
在这里插入图片描述
点击 Try it out 可以进行接口测试

填入参数，点击 Execute 按钮，发送请求进行测试

请求成功，可以看到请求执行路径、响应编码、响应数据等信息。

Springboot 整合 Swagger2 结束。

内容如有帮助，记得点赞哦~

敲代码的大雄

关注

1
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
Springboot 整合 Swagger2

Springboot 整合 Swagger2现如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger2 就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。项目整合后目录结构pom.xml 依赖<?xml version="1.0" encoding="UTF-8"?><project xml
复制链接

扫一扫