swagger3使用步骤

野性酷女 2024-03-16 14:06 50阅读 0赞

#### swagger3使用步骤 ####

*  1.添加依赖包
 *  2.配置类-SwaggerConfig(基于若依框架)
 *  3.swagger3默认地址

## 1.添加依赖包 ##

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>${
        swagger.version}</version>
        <exclusions>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>

## 2.配置类-SwaggerConfig(基于若依框架) ##

package com.ruoyi.web.core.config;
    
    import java.util.ArrayList;
    import java.util.List;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import com.ruoyi.common.config.RuoYiConfig;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.models.auth.In;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.ApiKey;
    import springfox.documentation.service.AuthorizationScope;
    import springfox.documentation.service.Contact;
    import springfox.documentation.service.SecurityReference;
    import springfox.documentation.service.SecurityScheme;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spi.service.contexts.SecurityContext;
    import springfox.documentation.spring.web.plugins.Docket;
    
    /**
     * Swagger2的接口配置
     * 
     * @author ruoyi
     */
    @Configuration
    public class SwaggerConfig
    {
        
        /** 系统基础配置 */
        @Autowired
        private RuoYiConfig ruoyiConfig;
    
        /** 是否开启swagger */
        @Value("${swagger.enabled}")
        private boolean enabled;
    
        /** 设置请求的统一前缀 */
        @Value("${swagger.pathMapping}")
        private String pathMapping;
    
        /**
         * 创建API
         */
        @Bean
        public Docket createRestApi()
        {
        
            return new Docket(DocumentationType.OAS_30)
                    // 是否启用Swagger
                    .enable(enabled)
                    // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                    .apiInfo(apiInfo())
                    // 设置哪些接口暴露给Swagger展示
                    .select()
                    // 扫描所有有注解的api，用这种方式更灵活
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    // 扫描指定包中的swagger注解
                    // .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
                    // 扫描所有 .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build()
                    /* 设置安全模式，swagger可以设置访问token */
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts())
                    .pathMapping(pathMapping);
        }
    
        /**
         * 安全模式，这里指定token通过Authorization头请求头传递
         */
        private List<SecurityScheme> securitySchemes()
        {
        
            List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
            apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
            return apiKeyList;
        }
    
        /**
         * 安全上下文
         */
        private List<SecurityContext> securityContexts()
        {
        
            List<SecurityContext> securityContexts = new ArrayList<>();
            securityContexts.add(
                    SecurityContext.builder()
                            .securityReferences(defaultAuth())
                            .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                            .build());
            return securityContexts;
        }
    
        /**
         * 默认的安全上引用
         */
        private List<SecurityReference> defaultAuth()
        {
        
            AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
            AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
            authorizationScopes[0] = authorizationScope;
            List<SecurityReference> securityReferences = new ArrayList<>();
            securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
            return securityReferences;
        }
    
        /**
         * 添加摘要信息
         */
        private ApiInfo apiInfo()
        {
        
            // 用ApiInfoBuilder进行定制
            return new ApiInfoBuilder()
                    // 设置标题
                    .title("标题：若依管理系统_接口文档")
                    // 描述
                    .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                    // 作者信息
                    .contact(new Contact(ruoyiConfig.getName(), null, null))
                    // 版本
                    .version("版本号:" + ruoyiConfig.getVersion())
                    .build();
        }
    }

## 3.swagger3默认地址 ##

> http://localhost:8080/swagger-ui/index.html  
> ![在这里插入图片描述][bf1de9fca59c42a4b38a2660f7662157.png]

[bf1de9fca59c42a4b38a2660f7662157.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/16/64039d42851448098dffa9672f99113e.png