swagger3的安装与使用

最新推荐文章于 2025-03-20 10:42:24 发布

chen_xionxion

最新推荐文章于 2025-03-20 10:42:24 发布

阅读量2k

点赞数

本文链接：https://blog.youkuaiyun.com/Adobe_java/article/details/122149295

版权

JAVA 专栏收录该内容

29 篇文章

订阅专栏

本文档详细介绍了Swagger3在SpringBoot项目中的安装步骤，包括添加依赖、配置调整、创建配置类和启动测试。同时，讨论了Swagger的使用，特别是在实体类和Controller类中的Swagger注解应用，帮助提升接口文档的编写效率，实现前后端高效协作。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Swagger是一个开源的软件框架，可以帮助开发人员设计、构建和使用Web服务，将代码与文档结合在一起，完美的解决了前后端分离的接口交接问题（编写接口文档，方便前后端交互），使开发人员将大部分精力集中到业务中，而不是文档的撰写，提高了开发效率也减少了开发成本。swagger官网

一、Swagger的安装

1、添加依赖

        <!--swagger依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!--swagger第三方插件-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2、添加配置

:Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher

spring:
  mvc:
    pathmatch:
      # 解决swagger3和springboot版本冲突
      matching-strategy: ant_path_matcher

# 用来开启或关闭文档的显示，线上不需要开启，开启会浪费资源
springfox:
  documentation:
    swagger-ui:
      enabled: true

3、创建配置类

package com.chen.config;

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 springfox.documentation.service.*;

@EnableOpenApi
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi(){
        //返回文档概要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                //不显示默认的错误页面接口
                .paths(PathSelectors.regex("/error").negate())
                .build();
    }

    /**
     * 生成接口信息，包括标题，联系人等
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("如有疑问,可联系百度")
                .contact(new Contact("百度","http://www.baidu.com","11017294@qq.com"))
                .version("1.0")
                .build();
    }
}

4、启动项目，测试swagger能否运行

如果出现错误请将上面的配置加到你的配置文件中
原生swagger界面网址：http://localhost:8080/swagger-ui/index.html
如果加入了上面的第三方依赖，请访问这个地址：http://localhost:8080/doc.html
项目路径根据自己项目的路径修改即可

如果你和我一样出现了以下问题，可以更换浏览器或给浏览器升级试试
以下问题是空对象的循环问题，由于不可遍历导致的，是swagger的前端问题
在这里插入图片描述

二、Swagger的使用（Swagger注解的使用）

1、在实体类的使用

使用了lombok插件，简化代码

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户信息实体")
public class User {
  @ApiModelProperty("主键")
  private Long id;

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

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

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

  private Date createTime;
  private Date updateTime;
  @Version
  private Integer version;
  @TableLogic
  private Integer deleted;
}

2、在Controller类的使用

@Api(tags = "用户信息增删改查类")
@RestController
public class UserController {

    @ApiOperation(value = "查询用户信息", notes = "根据姓名查询用户，可以增加年龄进行过滤")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "姓名", required = true),
            @ApiImplicitParam(name = "age", value = "年龄", required = false)
    })
    @PostMapping("selectUser")
    public List<User> selectUser(String name, Integer age){
        return new ArrayList<>();
    }

    @ApiOperation(value = "添加一个用户")
    @PostMapping("addUser")
    public void addUser(User user){}
}