springboot整合swagger-CSDN博客

本文链接：https://blog.csdn.net/m0_74197140/article/details/139000154

springboot整合swagger

本篇文章介绍了如何在springboot中使用swagger，包括在sprigboot2中整合swagger和在springboot3中整合swagger

介绍

什么是swagger

Swagger是一组围绕 OpenAPI 规范构建的开源工具，可以帮助您设计、构建、记录和使用 REST API，可以自动生成API文档。它能够减少编写API文档的工作量。

Swagger 常用于

生成API文档：Swagger 可以自动生成API的文档,包括API的描述、参数、请求例子、返回信息例子等。
API测试：Swagger生成的文档页面中有“Try it out”按钮,可以直接在页面上测试API接口。
代码生成：Swagger支持根据文档生成服务器端和客户端代码,支持的语言包括Java，PHP， Python，Ruby等。

swagger使用页面

swagger-ui界面
接口
实体类
接口测试
返回结果

springboot2整合swagger

要求： JDK8+

一、引入依赖

普通的swagger-ui页面，访问网址http://localhost:8080/swagger-ui.html

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

二、当高版本spring项目使用Swagger时

application.yml文件配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

创建配置类WebMvcConfigurer

package com.ljh.swagger.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {

    /**
     * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.html", "doc.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}

三、比较好的方案

在pox.xml中引入依赖(这个是github的)
访问网址：http://localhost:8080/doc.html

<!--  springfox-swagger2  -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

创建配置类WebMvcConfigurer

package com.ljh.swagger.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {

    /**
     * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.html", "doc.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}

大致配置类

package com.ljh.swagger.config;

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

import java.util.ArrayList;

@Configuration
@EnableSwagger2  //开启Swagger
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)  //是否启用Swagger
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.ljh.swagger.controller"))  //只扫描这个包中的接口
                // 配置如何通过path过滤,即这里只扫描请求以/开头的接口
                //.paths(PathSelectors.ant("ljh"))
                .build();
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        Contact contact = new Contact("小家伙", "http://localhost:8080/login", "1234567891@qq.com");
        return new ApiInfo(
                "小家伙的Swagger API接口文档",
                "勇往直前的路上一定充满艰辛",
                "v1.0",
                "http://localhost:8080/login",
                contact,
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }

}

四、其他皮肤

默认访问 http://localhost:8080/swagger-ui.html


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

bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

五、注解说明

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

springboot3整合swagger

要求： JDK17+

一、引入依赖

<!--springdoc依赖，作用是生成接口文档-->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>

二、Swagger初始化配置

package com.ljh.springboot3.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API接口文档")
                        .description("Mr.Liu的API接口文档")
                        .version("v1.0.0")
                        .contact(new Contact()
                                .name("Mr.Liu邮箱")
                                .email("1234567891@qq.com")
                        )
                );
    }
}

三、如果有拦截器，记得在拦截器中开放swagger接口

.excludePathPatterns("/swagger-ui/**","/v3/api-docs/**")

四、使用swagger注解

// controller控制层上的类
@Tag(name = "用户模块", description = "用户相关接口")
public class UserController

        // controller控制层上的方法
        @Operation(summary = "添加用户", description = "添加用户信息")
        private Result save(@RequestBody User user)

        @Operation(summary = "删除用户", description = "删除用户信息")
        private Result delete(@PathVariable("id") Integer id)

// pojo 实体类
@Schema(description = "用户实体类", title = "用户")
public class User

        // pojo 实体类中的方法
        @Schema(description = "用户名", title = "用户名")
        private String username;

五、默认访问地址

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

六、注解说明

Swagger注解	含义
@Tag	用在controller类上，描述此controller的信息
@Operation	用在controller的方法里，描述此api的信息
@Parameter	用在controller方法里的参数上，描述参数信息
@Parameters	用在controller方法里的参数上
@Schema	用于Entity，以及Entity的属性上
@ApiResponse	用在controller方法的返回值上
@ApiResponses	用在controller方法的返回值上
@Hidden	用在各种地方，用于隐藏其api