SpringBoot项目配置Swagger

ㅤㅤ 诚ㅤㅤ 2023-09-14 原文

SpringBoot项目配置Swagger

1、Swagger简介

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

当前项目配置好以后的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包

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

授权

文档管理
这里可以配置一些消息头和一些查询参数，可以添加多个

剩下的菜单就是读取的Controller的信息
这里是测试案例中配置的用户信息接口

3、Swagger常用注解说明

3.1、@ApiModel(“用户vo”)

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

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

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

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

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

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

@ApiOperation(value = “”),用来配置控制层中具体的方法，在Swagger文档的菜单项可以体现！如上图

有关SpringBoot项目配置Swagger的更多相关文章

ruby - 如何在 buildr 项目中使用 Ruby 代码？ - 2
如何在buildr项目中使用Ruby？我在很多不同的项目中使用过Ruby、JRuby、Java和Clojure。我目前正在使用我的标准Ruby开发一个模拟应用程序，我想尝试使用Clojure后端(我确实喜欢功能代码)以及JRubygui和测试套件。我还可以看到在未来的不同项目中使用Scala作为后端。我想我要为我的项目尝试一下buildr(http://buildr.apache.org/)，但我注意到buildr似乎没有设置为在项目中使用JRuby代码本身!这看起来有点傻，因为该工具旨在统一通用的JVM语言并且是在ruby中构建的。除了将输出的jar包含在一个独特的、仅限ruby
ruby-on-rails - 独立 ruby 脚本的配置文件 - 2
我有一个在Linux服务器上运行的ruby脚本。它不使用rails或任何东西。它基本上是一个命令行ruby脚本，可以像这样传递参数:./ruby_script.rbarg1arg2如何将参数抽象到配置文件(例如yaml文件或其他文件)中？您能否举例说明如何做到这一点？提前谢谢你。最佳答案首先，您可以运行一个写入YAML配置文件的独立脚本:require"yaml"File.write("path_to_yaml_file",[arg1,arg2].to_yaml)然后，在您的应用中阅读它:require"yaml"arg
ruby-on-rails - 项目升级后 Pow 不会更改 ruby 版本 - 2
我在我的Rails项目中使用Pow和powifygem。现在我尝试升级我的ruby版本(从1.9.3到2.0.0，我使用RVM)当我切换ruby版本、安装所有gem依赖项时，我通过运行railss并访问localhost:3000确保该应用程序正常运行以前，我通过使用pow访问http://my_app.dev来浏览我的应用程序。升级后，由于错误Bundler::RubyVersionMismatch:YourRubyversionis1.9.3,butyourGemfilespecified2.0.0，此url不起作用我尝试过的:重新创建pow应用程序重启pow服务器更新战俘
ruby-on-rails - 新 Rails 项目 : 'bundle install' can't install rails in gemfile - 2
我已经像这样安装了一个新的Rails项目:$railsnewsite它执行并到达:bundleinstall但是当它似乎尝试安装依赖项时我得到了这个错误Gem::Ext::BuildError:ERROR:Failedtobuildgemnativeextension./System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/bin/rubyextconf.rbcheckingforlibkern/OSAtomic.h...yescreatingMakefilemake"DESTDIR="cleanmake"DESTDIR="
Ruby Sinatra 配置用于生产和开发 - 2
我已经在Sinatra上创建了应用程序，它代表了一个简单的API。我想在生产和开发上进行部署。我想在部署时选择，是开发还是生产，一些方法的逻辑应该改变，这取决于部署类型。是否有任何想法，如何完成以及解决此问题的一些示例。例子:我有代码get'/api/test'doreturn"Itisdev"end但是在部署到生产环境之后我想在运行/api/test之后看到ItisPROD如何实现？最佳答案根据SinatraDocumentation:EnvironmentscanbesetthroughtheRACK_ENVenvironm
Ruby 从大范围中获取第 n 个项目 - 2
假设我有这个范围:("aaaaa".."zzzzz")如何在不事先/每次生成整个项目的情况下从范围中获取第N个项目？最佳答案一种快速简便的方法:("aaaaa".."zzzzz").first(42).last#==>"aaabp"如果出于某种原因你不得不一遍又一遍地这样做，或者如果你需要避免为前N个元素构建中间数组，你可以这样写:moduleEnumerabledefskip(n)returnto_enum:skip,nunlessblock_given?each_with_indexdo|item,index|yieldit
Vscode+Cmake配置并运行opencv环境(Windows和Ubuntu大同小异) - 2
之前在培训新生的时候，windows环境下配置opencv环境一直教的都是网上主流的vsstudio配置属性表，但是这个似乎对新生来说难度略高(虽然个人觉得完全是他们自己的问题)，加之暑假之后对cmake实在是爱不释手，且这样配置确实十分简单(其实都不需要配置)，故斗胆妄言vscode下配置CV之法。其实极为简单，图比较多所以很长。如果你看此文还配不好，你应该思考一下是不是自己的问题。闲话少说，直接开始。0.CMkae简介有的人到大二了都不知道cmake是什么，我不说是谁。CMake是一个开源免费并且跨平台的构建工具，可以用简单的语句来描述所有平台的编译过程。它能够根据当前所在平台输出对应的m
神州数码无线产品（AC+AP）配置 - 2
注意：本文主要掌握DCN自研无线产品的基本配置方法和注意事项，能够进行一般的项目实施、调试与运维AP基本配置命令AP登录用户名和密码均为：adminAP默认IP地址为：192.168.1.10AP默认情况下DHCP开启AP静态地址配置：setmanagementstatic-ip192.168.10.1AP开启/关闭DHCP功能：setmanagementdhcp-statusup/downAP设置默认网关：setstatic-ip-routegeteway192.168.10.254查看AP基本信息：getsystemgetmanagementgetmanaged-apgetrouteAP配
hadoop安装之保姆级教程（二）之YARN的配置 - 2
1.1.1 YARN的介绍为克服Hadoop1.0中HDFS和MapReduce存在的各种问题⽽提出的，针对Hadoop1.0中的MapReduce在扩展性和多框架⽀持⽅⾯的不⾜，提出了全新的资源管理框架YARN. ApacheYARN（YetanotherResourceNegotiator的缩写）是Hadoop集群的资源管理系统，负责为计算程序提供服务器计算资源，相当于⼀个分布式的操作系统平台，⽽MapReduce等计算程序则相当于运⾏于操作系统之上的应⽤程序。 YARN被引⼊Hadoop2,最初是为了改善MapReduce的实现，但是因为具有⾜够的通⽤性，同样可以⽀持其他的分布式计算模
Ruby 默认将 IRB 配置为 Pretty_Inspect - 2
我是ruby的新手，正在配置IRB。我喜欢pretty-print(需要'pp')，但总是输入pp来漂亮地打印它似乎很麻烦。我想做的是默认情况下让它漂亮地打印出来，所以如果我有一个var，比如说，'myvar'，然后键入myvar，它会自动调用pretty_inspect而不是常规检查。我从哪里开始？理想情况下，我将能够向我的.irbrc文件添加一个自动调用的方法。有什么想法吗？谢谢! 最佳答案 irb中默认pretty-print对象正是hirb被迫去做。Theseposts解释hirb如何将几乎所有内容转换为ascii表。虽

SpringBoot项目配置Swagger