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

已于 2024-04-24 21:46:08 修改
阅读量1.4k 收藏 25
点赞数 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","","");
    }
}

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

妄忧杂记
关注
  • 15
    点赞
  • 踩
  • 25
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
专栏目录
四、Java中SpringBoot组件集成接入【Knife4j接口文档（swagger增强）】
weixin_44330367的博客
01-08 1516
四、Java中SpringBoot组件集成接入【Knife4j接口文档（swagger增强）】
SpringBoot配置Swagger
m0_66508993的博客
11-15 185
SpringBoot配置Swagger
Swagger系列：Spring Boot 2.x集成Spring Doc（Swagger 3.0）
程序人生
09-10 1124
Swagger 是一个 RESTful API 的开源框架，它的主要目的是帮助开发者设计、构建、文档化和测试 Web API。Swagger 的核心思想是通过定义和描述 API 的规范、结构和交互方式，以提高 API 的可读性、可靠性和易用性，同时降低 API 开发的难度和开发者之间的沟通成本。Swagger它最初由Tony Tam在2011年创建，并在之后被SmartBear Software公司收购。
springboot集成swagger实现接口管理源码
05-09
springboot集成swagger源码，实现后台接口管理，提供后台开发人员接口测试，前端开发人员接调用，接口显示，接口查询和测试
SpringBoot3整合SpringDoc实现在线接口文档
最新发布
再小的帆也能远航，把分享变成一种习惯
06-18 1641
在现目前项目开发中，一般都是前后端分离项目。前端小姐姐负责开发前端，苦逼的我们负责后端开发事实是一个人全干，在这过程中编写接口文档就显得尤为重要了。然而作为一个程序员，最怕的莫过于自己写文档和别人不写文档大家都不想写文档，那这活就交给今天的主角Swagger来实现了①OpenApi是什么？OpenApi是一个用于描述、定义和共享文档的规范
2024年阿里首次分享：内部（珠峰版)Java笔记，看完直接斩获12家offer
m0_72758098的博客
05-03 431
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。深知大多数Java工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。
SpringBoot 集成接口文档，老鸟们也被打脸了！
飘渺Jam的博客
09-29 2300
之前我在SpringBoot老鸟系列中专门花了大量的篇幅详细介绍如何集成Swagger，以及如何对Swagger进行扩展让其支持接口参数分组功能。详情可见：SpringBoot 如何生成接口文档，老鸟们都这么玩的！ 可是当我接触到另一个接口文档工具 smart-doc后，我觉得它比Swagger更适合集成在项目中，更适合老鸟们。今天我们就来介绍一下smart-doc组件的使用，作为对老鸟系列文章的一个补充。 swagger vs smart-doc 首先我们先看一下Swagger组件目前存在的主要问题：
SpringBoot集成swagger接口文档
qq_42754347的博客
09-05 388
**SpringBoot+Swagger** 1. 先创建一个maven项目 在pom.xml中引入SpringBoot和swagger的依赖 org.springframework.boot spring-boot-starter-parent 1.5.6.RELEASE ...
【Java快速入门】-- SpringBoot集成swagger接口文档
xzpdxz的博客
03-16 644
依赖 <!-- swagger接口文档 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <dependency
springboot 接口文档_010 Spring Boot 集成Swagger接口文档
weixin_39796868的博客
12-08 56
Swagger 可以自动生成在线接口文档，界面可视化的同时保证了便利的测试接口。1. Swagger2 介绍Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。随着前后端技术的日渐成熟，前后端的交互就只有接口了，前端请求接口获取数据，所以接口的格式化也就相当重要，有一个标准格式的接口文...
SpringBoot集成Swagger2生成接口文档的方法示例
08-26
SpringBoot集成Swagger2生成接口文档的方法是开发RESTful API时常用的一种高效手段，它能够自动生成详细的API文档，便于开发者理解和使用。Swagger2是一个强大的工具，它可以与SpringBoot框架无缝结合，提供实时更新...
springboot集成swagger的demo
11-20
SpringBoot集成Swagger是一个高效的方法，用于为API提供交互式文档，极大地简化了接口文档的维护。Swagger是一个强大的工具，它允许开发人员通过简单的注解在代码中定义接口，然后自动生成文档，使得前后端协作更加...
springboot集成swagger过程解析
08-25
@Spring Boot集成Swagger是一个非常流行的解决方案，可以帮助开发者快速生成RESTful API文档。下面是@Spring Boot集成Swagger的详细过程解析。 一、添加依赖项 在@Spring Boot项目中，需要添加Swagger的依赖项，...
SpringBoot集成Swagger简单使用
12-22
总结来说，SpringBoot集成Swagger的步骤包括：引入相关依赖，创建Swagger配置类，编写API注解，通过Swagger UI访问和测试API。这个过程使得API的文档化和测试工作变得简单且高效，极大地提高了开发效率和API的可维护...
Spring Boot 集成 Swagger 在线接口文档
qq_40067747的博客
07-24 147
主要详细分析 Swagger 的优点以及 Spring Boot 集成 Swagger，包括配置，涉及到了实体类和接口类以及如何使用。最后通过页面测试，可以体验 Swagger 的强大之处，基本上是每个项目组中必备的工具之一，所以要掌握该工具的使用。
springboot集成swagger2接口文档
weixin_45986945的博客
06-26 106
springboot集成swagger2接口文档
Spring Boot配置Swagger
小小先生的博客
07-02 275
首先创建一个Spring Boot项目 导入jar包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency&gt
springboot 使用swagger
10-14
要在Spring Boot中使用Swagger，需要进行以下步骤： 1. 添加Swagger依赖 在pom.xml文件中添加以下依赖： ``` <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> ``` 2. 创建Swagger配置类 创建一个Swagger配置类，用于配置Swagger的一些基本信息和接口文档的生成规则。示例代码如下： ``` @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文档") .description("这是一个示例API文档") .version("1.0.0") .build(); } } ``` 3. 启动应用程序 启动应用程序后，在浏览器中访问http://localhost:8080/swagger-ui.html，即可看到生成的接口文档。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

打赏作者

妄忧杂记

整理不易，请多多打赏

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

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

打赏作者

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

抵扣说明：

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

余额充值