SpringBoot项目配置Swagger

这篇具有很好参考价值的文章主要介绍了SpringBoot项目配置Swagger。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

1、Swagger简介

根据在代码中使用自定义的注解来生成接口文档,这样做的好处是 在开发接口时可以通过swagger 将接口文档定义好提供给前端查询具体参数信息,同时也方便以后的维护。

当前项目配置好以后的Swagger原型:
SpringBoot项目配置Swagger

2、Boot整合Swagger案例(复制可直接使用)

2.1、Pom文件依赖配置

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.5</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>BootSwagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>BootSwagger</name>
    <description>BootSwagger</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!--Swagger-UI API文档生产工具-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-annotations</artifactId>
            <version>3.0.3</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

2.2、application.properties配置信息

#设置端口号
server.port=8088

#swagger配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.3、在启动类同级别创建Config包

SpringBoot项目配置Swagger

2.4、Swagger配置信息

2.4.1、配置跨域

package com.example.bootswagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;

@Configuration
public class GlobalCorsConfig {

    /**
     * 跨域处理
     */
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowCredentials(true);
        // 设置访问源地址
        config.addAllowedOriginPattern("*");
        // 设置访问源请求头
        config.addAllowedHeader("*");
        // 设置访问源请求方法
        config.addAllowedMethod("*");
        // 有效期 1800秒
        config.setMaxAge(1800L);

        // 添加映射路径,拦截一切请求
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);

        // 返回新的CorsFilter
        return new CorsFilter(source);
    }
}

2.4.2、Swagger自定义配置

package com.example.bootswagger.config;

import lombok.Builder;
import lombok.Data;

/**
 * Swagger自定义配置
 */
@Data
@Builder
public class SwaggerProperties {

    /**
     * API文档生成基础路径
     */
    private String apiBasePackage;

    /**
     * 是否要启用登录认证
     */
    private boolean enableSecurity;

    /**
     * 文档标题
     */
    private String title;
    /**
     * 文档描述
     */
    private String description;
    /**
     * 文档版本
     */
    private String version;
    /**
     * 文档联系人姓名
     */
    private String contactName;
    /**
     * 文档联系人网址
     */
    private String contactUrl;
    /**
     * 文档联系人邮箱
     */
    private String contactEmail;
}

2.4.3、Swagger API文档相关配置(Swagger名称,控制层包扫描)

注意.apiBasePackage(“com.example.bootswagger.controller”)是用来设置你的Controller所在包路径!

package com.example.bootswagger.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger API文档相关配置
 *
 * @author mac
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig extends SuperSwaggerConfig {


    @Override
    public SwaggerProperties swaggerProperties() {
        return SwaggerProperties.builder()
        		//设置Swagger扫描的Controller路径,只有扫描到了才会生成接口文档
                .apiBasePackage("com.example.bootswagger.controller")
                .title("swagger测试")
                .description("后台接口文档")
                .contactName("wranglings")
                .version("1.0")
                .enableSecurity(true)
                .build();
    }

}

2.4.4、Swagger基础配置

package com.example.bootswagger.config;

import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Collections;
import java.util.List;

/**
 * Swagger基础配置
 * @author mac
 */
public abstract class SuperSwaggerConfig {

    /**
     * 自定义Swagger配置
     */
    public abstract SwaggerProperties swaggerProperties();

    @Bean
    public Docket docket() {
        SwaggerProperties swaggerProperties = swaggerProperties();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo(swaggerProperties))
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage()))
                .paths(PathSelectors.any())
                .build();

        if (swaggerProperties.isEnableSecurity()) {
            docket.securitySchemes(Collections.singletonList(securitySchemes()))
                    .securityContexts(Collections.singletonList(securityContexts()));
        }
        return docket;
    }

    private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle() + " 服务API接口文档")
                .description(swaggerProperties.getDescription())
                .version(swaggerProperties.getVersion())
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))
                .version(swaggerProperties.getVersion())
                .build();
    }

    private ApiKey securitySchemes() {
        //设置请求头信息
        return new ApiKey("token", "accessToken", "header");
    }


    private SecurityContext securityContexts() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .operationSelector(operationContext -> true)
                .build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("xxx", "描述信息");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Collections.singletonList(new SecurityReference("Authorization", authorizationScopes));
    }

}

2.4.5、创建测试VO 和 Controller

创建用户Vo

package com.example.bootswagger.pojo.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户vo")
public class UserVo implements Serializable {

    @ApiModelProperty(value = "用户id")
    private Integer userId;

    @ApiModelProperty(value = "用户名称")
    private String userName;

    @ApiModelProperty(value = "用户密码")
    private String password;

}

创建Controller层

package com.example.bootswagger.controller;

import com.example.bootswagger.pojo.vo.UserVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.apache.commons.lang3.ObjectUtils;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户信息")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "查询用户详细信息")
    @GetMapping("/getInfo")
    public UserVo getInfo(Integer userId){
        UserVo userVo = new UserVo();
        if(ObjectUtils.isNotEmpty(userId)){
            userVo.setUserId(userId);
            userVo.setUserName("admin");
            userVo.setPassword("root");
        }
        return userVo;
    }

}

2.4.6、启动Swagger,重点菜单说明

链接: http://localhost:8088/doc.html
主页
SpringBoot项目配置Swagger
授权
SpringBoot项目配置Swagger
文档管理
这里可以配置一些消息头和一些查询参数,可以添加多个
SpringBoot项目配置Swagger
剩下的菜单就是读取的Controller的信息
这里是测试案例中配置的用户信息接口
SpringBoot项目配置Swagger

3、Swagger常用注解说明

3.1、@ApiModel(“用户vo”)

@ApiModel注解,用来配置Swagger文档中返回的对象名称,常用在实体类中;
如下图:
SpringBoot项目配置Swagger

SpringBoot项目配置Swagger

3.2、@ApiModelProperty(value = “用户id”)

@ApiModelProperty,用来配置Swagger文档中返回的对象的属性名称,如上图!
用户id、用户名称这些都是通过该注解配置的。

3.3、@Api(tags = “用户信息”)

@Api(tags = “”),用来配置控制层,在Swagger文档的菜单项可以体现!如下图
SpringBoot项目配置Swagger
SpringBoot项目配置Swagger

3.4、@ApiOperation(value = “查询用户详细信息”)

@ApiOperation(value = “”),用来配置控制层中具体的方法,在Swagger文档的菜单项可以体现!如上图文章来源地址https://www.toymoban.com/news/detail-419066.html

到了这里,关于SpringBoot项目配置Swagger的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 【解决问题】在SpringBoot中通过配置Swagger权限解决Swagger未授权访问漏洞

    Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。其中,Swagger-UI会根据开发人员在代码中的设置来自动生成API说明文档。若存在相关的配置缺陷,攻击者可以在未授权的状态下,翻查Swagger接口文档,得到系统功能API接口的详细参数,再

    2024年02月02日
    浏览(44)
  • SpringBoot使用Swagger配置API接口文档

    Swagger是一个用于设计、构建和文档化 RESTful API 的开源框架。它提供了一组工具,使得开发人员能够更轻松地定义、描述和测试API接口。 具体来说,Swagger包含以下几个核心组件: Swagger规范(Swagger Specification): 定义了一种格式化的API规范,使用YAML或JSON格式,用于描述API的各

    2024年02月05日
    浏览(49)
  • SpringBoot项目中使用Swagger2及注解解释(详细)

    SpringBoot项目中使用Swagger2及注解解释 一、导入Swagger坐标依赖 其中版本最常用2.9.2 二、在spring启动类添加注解@EnableSwagger2 @EnableSwagger2是springfox提供的一个注解,代表swagger2相关技术开启。会扫描当前类所在包,及子包中所有类型的swagger相关注解,做swagger文档的定制 三、启动

    2023年04月18日
    浏览(82)
  • SpringBoot整合Swagger踩坑-项目启动报错与swagger-ui.html请求404无法访问

    依赖 常见依赖接入方式如下: springfox推荐 依赖接入方式如下: 建议使用推荐的方式,可以协助我们解决404异常的问题。 配置 依赖导入完成后创建 SwaggerConfig.java 配置: 报错信息: org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’; n

    2024年02月01日
    浏览(41)
  • springboot配置swagger3-springfox实现

    springfox 之前配置需要声明多个依赖,到了 3 直接声明一个 starter 就行了. springboot 版本 2.7.7 springfox-boot-starter 版本 3.0.0 声明依赖 声明yml配置 bean配置

    2024年02月12日
    浏览(36)
  • Springboot配置Swagger展示API文档并进行接口测试(doc.html、swagger-ui.html)

    三、创建一个测试接口 http://localhost:8080/doc.html http://localhost:8080/swagger-ui.html

    2024年02月10日
    浏览(41)
  • springboot2.7以上版本配置swagger3.0.0版本浏览器无法打开swagger-ui

    1.最实用解决方式:将pom里的swagger依赖降到2.9.0即可 过低无法启动项目 1.2 Springboot2.6以后将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser Springfox 使用的路径匹配是基于AntPathMatcher的,而Spring Boot 2.6.X使用的是PathPatternMatcher 2.3.0.0版本swagger2访问地址为:http://loca

    2024年02月11日
    浏览(35)
  • springboot和vue:五、RESTful服务+HTTP状态码+swagger配置

    每一个URI代表一种资源 客户端使用GET、POST、PUT、DELETE四种表示操作方式的动词对服务端资源进行操作:POST用于新建资源(也可以用于更新资源),PUT用于更新资源 资源的表现形式是JSON或者HTML。 客户端与服务端之间的交互在请求之间是无状态的,从客户端到服务端的每个请

    2024年02月07日
    浏览(39)
  • springboot 集成 Swagger2 配置以及常用注解的说明和使用 ( 超详细)

    一、注解的使用 和 说明 结构化说明如下: @Api:用在请求的类上,表示对类的说明      tags=\\\"说明该类的作用,可以在UI界面上看到的注解\\\"    (也就是给类取别名)     value=\\\"该参数没什么意义,在UI界面上也看到,所以不需要配置\\\"    @ApiOperation:用在请求的方法上,说

    2024年02月03日
    浏览(47)
  • Springboot 实践(2)MyEclipse2019创建项目修改pom文件,加载springboot 及swagger-ui jar包

    MyEclipse2019创建工程之后,需要添加Springboot启动函数、添加application.yml配置文件、修改pom文件添加项目使用的jar包。 添加Springboot启动函数 创建文件存储路径 (1)右键单击“src/main/java”文件夹,弹出对话框输入路径名称“com.SJL.action.app”,点击“finish”按钮,完成路径创建。

    2024年02月12日
    浏览(43)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包