教你springboot配置swagger实现接口文档

已于 2023-01-18 22:04:48 修改
阅读量3.9k 收藏 16
点赞数 4
分类专栏： springboot 文章标签： spring boot java mybatis
于 2022-09-16 18:52:57 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/xc9711/article/details/126893012
版权

前言

什么是Swagger?
在正式要配置它之前我们应该要对它有所了解，所谓swagger，简单说就是专门配置接口文档说明的一个依赖工具。
swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。
以上也就是它的作用，别的就不多说了，需要了解更多就自己去百度查找资料，最重要的还是如何去配置和使用它

创建springboot项目

那么,我们一开始应该要有一个springboot项目，本次我会从零开始构建。
本次使用的是IDEA进行创建springboot项目

FILE—>NEW—>PROJECT创建项目

在这里插入图片描述

选择Maven类型，并下一步输入项目名、组织名然后点击FINISH创建

在这里插入图片描述
在这里插入图片描述
初始项目结构如图
在这里插入图片描述

创建不同层级文件夹并搭建框架

搭建完框架的项目截图
在这里插入图片描述

testMapper代码

package com.testSwagger.mapper;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface testMapper {
}

SwaggerApplication代码

package com.testSwagger;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
// 声明springboot
@SpringBootApplication
// 指定连接数据库的mapper区
@MapperScan("com.testSwagger.mapper")
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

application.yml代码

# 指定启动路径
server:
  port: 9111
  servlet:
    # 项目的路径，配置如下之后，它的路径为http:locahost:9111/swagger
    context-path: /swagger
# 为启动项目，需要配置一个数据库进行连接
spring:
  datasource:
    driver-class-name: com.mysql.jdbc.Driver
    url: jdbc:mysql://数据库url
    username: 连接数据库的用户名
    password: 连接数据库的密码

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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>swagger</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <!--    编码格式-->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.5</version>
    </parent>
    <dependencies>
        <!--        springboot-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!--        mybatis-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>3.4.3</version>
        </dependency>
        <!--        mysql-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.26</version>
        </dependency>
<!--        lombok-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.18</version>
            <optional>true</optional>
        </dependency>
    </dependencies>
    <!--    打包配置-->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

以上，我们基础的springboot项目就搭建好了，接下来正式的去实现swagger

配置swagger

首先得说一下它的官方文档链接，不过它都是英文不好懂，大家可跟着我的步骤去构建

swagger文档链接

本次项目使用的是swagger2
同时说一点： swagger分为swagger2 和swagger3两个常用版本。二者区别不是很大，主要对于依赖和注解进行了优化。swagger2需要引入2个jar包，swagger3只需要一个，用起来没有什么大的区别。下面以swagger2为例。

ps: 如果你需要使用的是swagger3或者更高版本
请在application.yml文件添加如下配置

spring:
    mvc:
        path match:
            matching-strategy: ant_path_matcher

添加swagger的pom依赖

        <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>

添加config配置

在config文件夹下，创建swagger配置的java文件
在这里插入图片描述
更新于2023-01-15 09:11:35

package com.testSwagger.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.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;


@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .enable(true)
                .host("localhost:9111")
                .select()
                //这里指定Controller扫描包路径(项目路径也行)
                .apis(RequestHandlerSelectors.basePackage("com.testSwagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger测试文档")
                .description("swagger测试的API文档-swageer2")
                .contact(new Contact("相与还","http://localhost:9111/swagger/doc.html","a1947934569@163.com"))
                .termsOfServiceUrl("http://localhost:9111/swagger/doc.html")
                .version("1.0.0")
                .build();
    }
}

创建swagger文档案例

新建实体类并添加swagger注解

在这里分别使用了 @ApiModel注解和 @ApiModelProperty 注解定义了实体的名称和字段的名称，方便生成接口文档时展示。

添加实体类的swagger注解,名称自取
在这里插入图片描述

package com.testSwagger.bean;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("swagger实体类")
public class BeanTest {
    @ApiModelProperty("名称")
    private String name;
    @ApiModelProperty("年龄")
    private String age;
}

创建controller并添加swagger注解

这里使用了@Api注解和@ApiOperation注解分别标注了接口组名和接口的名称。

新建一个controller文件，任意取名
在这里插入图片描述

package com.testSwagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/swagger")
@Api(value = "测试controller",tags = {"接口"})
public class SwaggerController {

    @ApiOperation("接口1作用")
    @GetMapping("controller1")
    public String controller1() {
        return "测试接口1";
    }

    @ApiOperation("接口2作用")
    @PostMapping("controller2")
    public String controller2(){
        return "测试接口2";
    }
}

访问接口文档

到这个地方，我们就可以访问我们的接口文档了
前面我的yml配置的访问地址是/swagger
在这里插入图片描述

更新于2023-01-15 09:12:49
因此swagger2访问的链接是:

http://localhost:9111/swagger/swagger-ui.html

假如你使用的是swagger3
那么按照本项目的配置访问链接为

http://localhost:9111/swagger/swagger-ui/index.html

运行后的项目截图为:
在这里插入图片描述
在这里插入图片描述
更新于2023-01-15 09:14:54

进阶

以上，你会发现，它的界面太丑了，看上去体验不是很好，那么我接下来，将变更它的UI

引入swagger的UI依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

然后你直接访问链接
http://localhost:9111/swagger/doc.html

也可以按照代码

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger测试文档")
                .description("swagger测试的API文档-swageer2")
                .contact(new Contact("相与还","http://localhost:9111/swagger/doc.html","a1947934569@163.com"))
                .termsOfServiceUrl("http://localhost:9111/swagger/doc.html")
                .version("1.0.0")
                .build();
    }

点击swagger基础界面的
Terms of service也可以跳转到美化后的Swagger的UI界面
虽然当前配置下可以点击
相与还-Website进行跳转到美化后的Swagger的UI界面，但是一般情况它可能用来写自己个人网址还是什么比较多吧，也可以和我一样的写法。
在这里插入图片描述
然后美化后的UI截图如下:
在这里插入图片描述
在这里插入图片描述

明显比之前的好看很多，到现在已经可以进行开发完成接口文档了。

问题处理

假如出现访问swagger接口文档失败，报错404，则新建一个配置文件，配置文件名称任意，继承自WebMvcConfigurer
代码例子:

public class exampleConfig implements WebMvcConfigurer {
	    /**
     * 防止/swagger-ui.html 404错误
     *
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 开放优化后的swagger的ui访问路径
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

结语

以上就是swagger文档的配置和使用步骤，如有新内容将在本文章更新

相与还
关注
  • 4
    点赞
  • 踩
  • 16
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
Spring Boot-集成Swagger
2401_84048034的博客
05-06 1016
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。深知大多数Java工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。
springboot集成swagger实现接口管理源码
05-09
接下来，我们需要配置Swagger。创建一个配置类，例如`SwaggerConfig.java`，并在其中使用`@EnableSwagger2`注解开启Swagger支持。然后，定义一个`Docket`实例，通过`select()`方法选择需要暴露的API，并通过`apiInfo...
swagger -- 前后端分离的API接口
衍射的博客
11-09 2088
文章目录一、背景二、swagger介绍三、在maven+springboot项目中使用swagger 一、背景 现在的网站大多都是前后端分离式的开发，前后端都衍生出了自己的框架。现在前后端交互的唯一方式就是API接口。 曾经前后端交互都需要后端人员手动编写API接口文档，规定路径、请求方式、返回类型，这样效率很低。 swagger就是更好地书写API文档的框架。 二、swagger介绍 sw...
【工具】springboot集成swagger（接口文档工具）
最新发布
qq_37449606的博客
04-24 1394
复杂的事情简单化，大神封装好了，我们拿来直接用就好：只需（1）依赖（2）创建一个配置文件。
Swagger(一) Swagger/Springfox 入门简介
奥迪的博客
09-12 7674
Swagger/Springfox 入门简介 一、 Swagger 简介 1 前言 接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。 很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。 如果接口文档可以实时动态生成就不会出现上面问题。 Swagger 可以完美的解决上面..
API接口文档利器：Swagger 和 接口调试利器：Postman
m0_63615119的博客
08-23 1945
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务它的主要作用是：使得前后端分离开发更加方便，有利于团队协作接口的文档在线自动生成，降低后端开发人员编写接口文档的负担功能测试Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。
swagger接口测试工具介绍及使用
sunzixiao的博客
06-21 7042
在web开发中需要对接口进行测试，这时就需要用到测试工具。一般使用较多的测试工具有swagger（丝袜哥）和postman（邮递员）。在这里来总结一下swagger的使用方法和步骤。Swagger 官网地址：https://swagger.io/Swagger 有了丝袜哥，只需要在类或者接口等地方加上几个注解，然后在浏览器通过对应的url访问swagger的ui界面，这个界面上会展示接口的所有信息，点击对应的接口即可进行测试，非常方便，界面也做的非常赏心悦目。 Spring，迅速将Swagger规范纳入自身
spring-boot之接口文档Swagger配置使用
weixin_51627264的博客
03-29 833
bean‘documentationPluginsBootstrapper 错误，还可以在application.properties里面加"spring.mvc.pathmatch.matching-strategy= ANT_PATH_MATCHER"html==> 后端。伪造后端数据，json。访问地址http://localhost:8080/swagger-ui/●后端:后端控制层，服务层,数据访问层[后端团队]4.配置Swagger ==> Config。●前端:前端控制层，视图层[前端团队]
springboot整合swagger2
m0_46487331的博客
06-08 1534
springboot整合swagger
SpringBoot整合Swagger3生成接口文档过程解析
08-18
配置Swagger3Config类，用于生成接口文档： ```java @Configuration public class Swagger3Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) ...
SpringBoot集成Swagger2生成接口文档的方法示例
08-26
SpringBoot集成Swagger2生成接口文档的方法是开发RESTful API时常用的一种高效手段，它能够自动生成详细的API文档，便于开发者理解和使用。Swagger2是一个强大的工具，它可以与SpringBoot框架无缝结合，提供实时更新...
Spring boot集成swagger2生成接口文档的全过程
08-25
2. 在Spring Boot的配置类中，我们需要创建一个`Docket`实例来配置Swagger2。例如： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket...
详解SpringBoot结合swagger2快速生成简单的接口文档
08-26
SpringBoot结合Swagger2快速生成简单的接口文档 SpringBoot是一款流行的Java框架，Swagger2是一个流行的API文档生成工具。本文将详细介绍如何使用SpringBoot结合Swagger2快速生成简单的接口文档。 为什么选择...
Swagger接口在线文档
Limitless* 的博客
11-18 5520
swagger是什么？ Swagger围绕OAS构建RESTFUL文档； Swagger动态生成接口定义文档； Swagger易用免费且开源； swagger就是将项目中所有的接口展现在页面上，并且可以通过页面进行简单的调用和测试。 swagger工具介绍 Swagger Editor：开源编辑器； Swagger UI：呈现可交互在线文档； Swagger Codegen：生成调用代码的工具； Swagger Springfox：Swagger集成Spring生态； swagger有什么用 支..
Swagger2的使用和配置
weixin_44175409的博客
10-17 1479
1.简介 帮助前端开发人员便捷调用后端api的，减少不必要的沟通联调，自动生成接口文档，并且也可以像postman一样发送https请求的一款自带UI的插件2.注解@Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源参数： @ApiOperation()：用于方法，表示一个http请求访问该方法的操作参数： @ApiModel()：用于响应实体类上，用于说明实体作用参数： @ApiModelProperty：用在属性上，描述实体类的属性参数： @
Springboot集成Swagger实现接口文档自动生成
悠杨的专栏
11-25 907
在实时接口文档的生成方案中，Swagger是最具影响力的一个。本文介绍了在Springboot项目中如何集成Swagger2和3，来实现接口文档的自动生成和更新的方法。
SpringBoot配置Swagger接口文档及美化增强依赖
qq_62015542的博客
12-07 1419
在springboot配置不同的swagger接口文档
接口工具--Swagger
Skiray的博客
08-03 444
引入依赖 <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> </dependency> <!--swagger ui--> <dependency> <groupId>io.springfox</groupId&gt
springboot配置swagger
08-03
### 回答1： SpringBoot 配置Swagger 可以参考以下步骤：1. 在pom.xml中添加Swagger2依赖；2. 在SpringBoot启动类中添加@EnableSwagger2注解；3. 创建配置类Swagger2；4. 在配置类中配置Swagger2信息；5. 启动SpringBoot项目，访问Swagger2页面。 ### 回答2： Spring Boot是一个基于Java的快速开发框架，可以简化Java应用的搭建和开发过程。Swagger是一个RESTful API文档生成工具，它可以通过注解来生成API文档，并且提供了一个可交互的UI界面，方便开发人员查看和测试API接口。 要在Spring Boot项目中配置Swagger，需要进行以下步骤： 1. 导入Swagger依赖：在项目的pom.xml文件中添加Swagger的依赖项，通常是通过引入`springfox-swagger2`和`springfox-swagger-ui`这两个依赖来实现。 2. 创建Swagger配置类：在项目中创建一个Swagger的配置类，用于配置Swagger的相关信息和接口扫描规则。可以在配置类中使用`@EnableSwagger2`注解来启用Swagger。 3. 配置Swagger的基本信息：在配置类中使用`Docket`类的实例来配置Swagger的基本信息，比如Swagger接口文档的版本、标题、描述、联系人等。可以通过`apiInfo`方法来设置这些信息。 4. 配置接口扫描规则：在配置类中使用`select`方法来设置Swagger要扫描的接口规则，比如指定要扫描的包路径，或者使用`RequestHandlerSelectors`类提供的方法来选择要包含的接口。 5. 配置Swagger UI界面：在配置类中使用`apis`方法来设置Swagger要显示的接口，可以选择显示所有接口，或者只显示带有特定注解的接口。可以使用`PathSelectors`类提供的方法来选择要显示的接口。 6. 启动项目并访问Swagger UI：完成上述配置后，启动Spring Boot项目，并访问Swagger UI界面，通常是通过在浏览器中访问`http://localhost:port/swagger-ui.html`来查看API文档。 以上就是在Spring Boot项目中配置Swagger的基本步骤。配置完毕后，开发人员就可以方便地查看和测试API接口，提高开发效率。 ### 回答3： Spring Boot是一个开源的Java开发框架，可以简化Spring应用程序的配置和开发过程。Swagger是一个用于构建、文档化和调试RESTful API的工具。在Spring Boot项目中配置Swagger可以使得我们更方便地管理和测试API接口。 要配置Swagger，我们需要在Spring Boot项目的pom.xml文件中添加Swagger的依赖。可以通过以下代码完成添加： ```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> ``` 添加依赖后，我们需要创建一个配置类来配置Swagger。可以创建一个名为SwaggerConfig的类，并通过@Configuration注解将其标记为配置类。在SwaggerConfig类中，我们需要使用@EnableSwagger2注解启用Swagger，并创建一个Docket bean来配置Swagger的一些参数。 以下是一个示例的Swagger配置类代码： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.api")) .paths(PathSelectors.any()) .build(); } } ``` 在上述代码中，我们通过RequestHandlerSelectors.basePackage()方法指定了API接口所在的包路径，通过PathSelectors.any()方法指定了所有路径都被扫描。这样配置后，Swagger就可以扫描到我们想要展示的API接口。 最后，在启动类中添加@EnableSwagger2注解，启用Swagger。然后运行项目，访问Swagger UI界面（默认路径为：http://localhost:8080/swagger-ui.html），就可以看到API接口的文档、测试和调试信息了。 通过以上步骤，我们就成功地配置了Swagger在Spring Boot项目中。使用Swagger可以方便地对API进行管理和测试，提高了开发效率。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

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

余额充值