【工具】springboot集成swagger（接口文档工具）

已于 2024-04-24 21:46:08 修改
阅读量1.8k 收藏 26
点赞数 15
分类专栏： 工具 文章标签： spring boot 后端 java
于 2024-04-24 19:41:33 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_37449606/article/details/138162870
版权

文章目录

复杂的事情简单化，大神封装好了，我们拿来直接用就好：只需
（1）依赖
（2）创建一个配置文件
在这里插入图片描述

1.pom.xml导入依赖

注意springboot版本和swagger的版本，我springboot版本是2.4.0

	<!--swagger的依赖-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

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

2.swagger的访问路径

http://ip:端口号/swagger-ui.html(例如：http://localhost:8086/swagger-ui.html)

3.创建配置文件：常用的配置汇总（具体释义可查看案例）

package com.example.common;  //这里根据项目实际包路径修改

import cn.hutool.http.HttpResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import javax.servlet.http.HttpServletRequest;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Autowired
    Environment environment;

    @Bean
    public Docket docket() {  //这个是在swagger-ui这个依赖中
        //配置哪些环境可以访问swagger
        Profiles profiles = Profiles.of("dev", "test");
        boolean isEnable = environment.acceptsProfiles(profiles);

        Parameter token = new ParameterBuilder().name("token")
                .description("用户登录令牌")
                .parameterType("query") //如果改成header,则接收token时需要写@RequestHeader("token")String token
                .modelRef(new ModelRef("String"))
                .required(true)  //代表此字段必填
                .build();
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(token);

        return new Docket(DocumentationType.SWAGGER_2)
                /*配置哪些环境可以访问swagger*/
                .enable(isEnable)
                /*配置全局参数*/
                .globalOperationParameters(parameters)

                /*配置忽略一些参数*/
                .ignoredParameterTypes(HttpServletRequest.class, HttpResponse.class)

                /*配置swagger页面的基本信息*/
                .apiInfo(apiInfo())

                /*下面为一些配置*/
                .select()
                //扫描controller层的包
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //过滤：设置请求路径，这里是带有admin的请求路径,注意需要加上前缀
                // .paths(PathSelectors.ant("/api/admin/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact concat = new Contact("后端管理系统", "springboot后端接口", "163.com");
        return new ApiInfo(
                "SpringBoot项目集成Swagger实例文档",
                "欢迎",
                "API V1.0",
                "可修改成公司或组织的域名",   //公司或组织的url
                concat,
                "",
                "",
                Collections.emptyList());
    }


    //如果使用分组就是设置不同的对象
    @Bean
    public Docket docket1() {  //这个是在swagger-ui这个依赖中
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("第一组")
                .select().paths(PathSelectors.ant("/api/admin/**")).build();
    }
    @Bean
    public Docket docket2() {  //这个是在swagger-ui这个依赖中
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("第2组")
                .select().paths(PathSelectors.ant("/api/audit/**")).build();
    }
}

4.案例

实际项目中swagger配置文件中用不到的属性可以注释掉

4.1 页面基本信息部分：调用apiInfo

在这里插入图片描述

   @Bean
    public Docket docket() { 
        return new Docket(DocumentationType.SWAGGER_2)
                /*配置swagger页面的基本信息*/
                .apiInfo(apiInfo())
                .build();
    }

//可以根据需要配置相关的值
    private ApiInfo apiInfo() {
        Contact concat = new Contact("后端管理系统", "springboot后端接口", "163.com");
        return new ApiInfo(
                "SpringBoot项目集成Swagger实例文档",
                "欢迎",
                "API V1.0",
                "可修改成公司或组织的域名",   //公司或组织的url
                concat,
                "",
                "",
                Collections.emptyList());
    }

在这里插入图片描述

4.2 接口部分

（1）apis：com.example.controller为包路径，不加过滤pahts时代表扫描所有controller层接口
（2）paths：/api/admin/** 为指定的接口范围（项目中有api前缀的必须加上）

 @Bean
    public Docket docket() {  //这个是在swagger-ui这个依赖中
        return new Docket(DocumentationType.SWAGGER_2)
       
                /*下面为一些配置*/
                .select()
                //扫描controller层的包
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //过滤：设置请求路径，这里是带有admin的请求路径,注意需要加上前缀
                 .paths(PathSelectors.ant("/api/admin/**"))
                .build();
    }

apis、paths其他的属性根据不同的需要去选择
在这里插入图片描述

4.3配置忽略一些参数

比如下面的示例，查看接口文档时就看不到request response参数

.ignoredParameterTypes(HttpServletRequest.class, HttpResponse.class)

4.4 配置全局参数

比如配置一个全局的token

 @Bean
    public Docket docket() {  //这个是在swagger-ui这个依赖中
    
        Parameter token = new ParameterBuilder().name("token")
                .description("用户登录令牌")
                //如果query改成header,则接收token时需要写public Result findList(@RequestHeader("token")String token){}
                .parameterType("query") 
                .modelRef(new ModelRef("String"))
                .required(true)  //必填
                .build();
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(token);

        return new Docket(DocumentationType.SWAGGER_2)
                /*配置全局参数*/
                .globalOperationParameters(parameters)

                /*下面为一些配置*/
                .select()
                //扫描controller层的包
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //过滤：设置请求路径，这里是带有admin的请求路径,注意需要加上前缀
                 .paths(PathSelectors.ant("/api/admin/**"))
                .build();
    }

4.5配置哪些环境可以访问swagger

(1)写成public Docket docket( Environment environment) 与 @Autowired注入的方式是一样的
(2)先参考spingboot多环境配置https://blog.csdn.net/qq_37449606/article/details/138161809

 @Autowired
    Environment environment;

    @Bean
    public Docket docket() {  //这个是在swagger-ui这个依赖中
        //配置哪些环境可以访问swagger
        Profiles profiles = Profiles.of("dev", "test");
        boolean isEnable = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                /*配置哪些环境可以访问swagger*/
                .enable(isEnable)
                .build();
    }

4.6分组

每个组下面放什么接口可以自定义
实现：创建多个bean对象
在这里插入图片描述

    //如果使用分组就是设置不同的对象
    @Bean
    public Docket docket1() {  //这个是在swagger-ui这个依赖中
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("第一组")
                .select().paths(PathSelectors.ant("/api/admin/**")).build();
    }
    @Bean
    public Docket docket2() {  //这个是在swagger-ui这个依赖中
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("第2组")
                .select().paths(PathSelectors.ant("/api/audit/**")).build();
    }

5.注解

实体类的注解
@ApiModel
@ApiModelProperty
controller层接注解
@Api
@ApiOperation
@ApiImplicitParams
@ApiImplicitParam

5.1实体中的注解

更加方便阅读
@ApiModel(“用户实体”) 【定义实体的名称】
@ApiModelProperty(value=“用户名” , example =“zhangs” ) 【定义属性的名称，example为示例】

@Data
@Table(name = "admin")
@ApiModel("用户实体")
public class Admin {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;

    @ApiModelProperty(value="用户名" , example ="zhangs" )
    private String name;
    @ApiModelProperty("密码")
    private String password;
    private Integer age;
    private String phone;
    private String sex;
    private String role;
}

在这里插入图片描述
在这里插入图片描述

5.2controller注解

@Api
@ApiOperation
@ApiImplicitParams
@ApiImplicitParam

@Api(tags ="用户相关的请求")
@RestController
@RequestMapping("/admin")
public class AdminController {

    @ApiOperation("查询用户接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户名", dataType = "String", paramType = "header", defaultValue = "zhangsan", example = "lisa"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "String", paramType = "header", defaultValue = "zhangsan", example = "lisa")
    })
    @GetMapping("/findUserTest")
    public Admin findUserList(String name, String password){
        return new Admin(1,"zhangsan","123456",15,"176","女","role","","");
    }

    @ApiOperation("用对象格式接收的接口")
    @GetMapping("/findUserTest2")
    public Admin findUserList2(Admin admin){
        return new Admin(1,"zhangsan","123456",15,"176","女","role","","");
    }

    @ApiOperation("用json格式接收的接口")
    @GetMapping("/findUserTest3")
    public Admin findUserList3(@RequestBody  Admin admin){
        return new Admin(1,"zhangsan","123456",15,"176","女","role","","");
    }
}

在这里插入图片描述
在这里插入图片描述
在这里插入图片描述
在这里插入图片描述

森林守护者
关注
专栏目录
SpringBoot集成Swagger接口文档
hkl_Forever的博客
09-20 299
三、以上配置完成后，访问。
SpringBoot整合Swagger生成接口文档
weixiaohuai的博客
10-01 648
一、简介 Swagger是一个功能强大的API框架，它支持在线文档的查看以及在线文档的测试，方便我们前后端开发人员对接。Swagger使用起来也很简单，只需要加入swagger对应的依赖以及在controller类以及方法中加入相应的注解说明，swagger就会帮我们自动生成API接口文档。 本文主要通过一个简单的模拟增删查改功能实现springboot整合swagger2生成Restful ...
Springboot集成Swagger
anji_navinfo的博客
03-27 554
spring boot swagger
Spring Boot-集成Swagger
最新发布
2401_86984462的博客
09-07 2056
再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及。
Spring Boot——集成Swagger
一心同学的博客
12-31 4193
保姆级别讲解Swagger工具，讲解关于Swagger的各种实用知识点以及注意事项。
Springboot Swagger2 快速详细配置（简单易学代码注释多）
天道酬勤
04-02 668
一、简介 一份解决前后端分离开发的接口文档，详细解释自行百度。 二、使用前提 jdk 1.8 + Springboot 三、配置 创建一个Springboot-web工程 添加Maven依赖 <!-- swagger2 文档--> <dependency> <groupId>io.springfox</groupId> &lt...
SpringBoot集成Swagger2生成接口文档的方法示例
08-26
SpringBoot集成Swagger2生成接口文档的方法是开发RESTful API时常用的一种高效手段，它能够自动生成详细的API文档，便于开发者理解和使用。Swagger2是一个强大的工具，它可以与SpringBoot框架无缝结合，提供实时更新...
springboot集成swagger实现接口管理源码
05-09
SpringBoot集成Swagger实现接口管理是现代Web开发中的一项重要技术，它使得API文档的创建、维护和使用变得更加方便。Swagger是一款强大的RESTful API文档工具，它允许开发者通过注解来描述Spring MVC的Controller...
【SpringBoot笔记11】SpringBoot框架集成Swagger2文档
✅ Java 开发工程师，从事 Web 应用程序的研发，擅长 Spring、SpringBoot 等技术。 ✅ 热爱编程，业余时间学习新知识，通过 CSDN 记录学习心得和笔记内容。
10-24 1094
Swagger是一款API文档工具，SpringBoot中集成Swagger之后，通过访问swagger-ui前端界面，就可以查看当前工程里面所有对外提供的接口以及出入参之后，不仅如此，swagger还可以和postman一样，直接调用后端接口地址，这在前后端分离模式下，swagger就变得非常有用了，因为前端开发人员，只需要看swagger接口文档，就可以进行开发，而不需要我们后端开发人员自己写个接口文档。SpringBoot没有专门提供swagger的starter启动器，所以我们需要自己单独引入s
springboot集成swagger
02-22
编译工具是idea,jdk是1.8.9,管理工具是maven 基本的springboot项目集成swaggerui,项目启动成功后,swaggerui可正常访问,进行后端测试
SpringBoot集成swagger2
m0_37730948的博客
04-20 619
​ 在当今前后端框架流行的时代，一个完整并且规范的接口文档是必不可少的。Swagger是一款Restful接口风格文档在线自动生成、接口功能测试的集成插件，用于生成、描述和可视化Restful风格的Web服务。软件可以实现接口文档同API始终保持同步。同过去的离线接口文档相比起来，整体提高了项目的开发效率，减少了前后端成员之间的非必要沟通。​ 官网地址：https://swagger.io/
Springboot集成swagger
CharlieChen的专栏
03-04 885
1. 打开浏览器，访问：https://start.spring.io/ 2. 根据页面提示，选择构建工具，开发语言，项目信息等。 使用IDE导入项目 添加相关依赖 添加 Maven 相关依赖，这里需要添加上WEB和SWAGGER依赖。 WEB依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-...
springboot 集成swagger
噗嗤
10-12 539
开发者的伙伴，在线生成文档
SpringBoot集成 Swagger
m0_58414041的博客
07-27 453
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口，所以 API 文档变成了前后端开发人员联系的纽带，变得越来越重要。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

森林守护者

整理不易，请多多打赏

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值