Swagger3配置

ゝ一世哀愁。 2023-01-10 01:26 154阅读 0赞

使用Swagger3去简化以前Swagger2的配置

引入依赖

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>
            
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>3.0.2</version>
            </dependency>

配置类

package com.tgpms.config;
    
    import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.http.HttpMethod;
    import springfox.documentation.builders.*;
    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.ArrayList;
    import java.util.Collections;
    import java.util.List;
    
    /**
     * swagger3 配置
     * @author jiangli
     * @since 2021/1/22 10:04
     */
    @Configuration
    @EnableKnife4j  // 访问路径ip:port/doc.html
    public class Swagger3Config {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build()
    //                .globalRequestParameters(getGlobalRequestParameters())
                    .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                    .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                    .globalResponses(HttpMethod.DELETE, getGlobalResponseMessage())
                    .globalResponses(HttpMethod.PUT, getGlobalResponseMessage())
                    //添加登录认证
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts());
        }
    
        /**
         * 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
         */
        private ApiInfo apiInfo() {
            // 获取工程名称
            String projectName = System.getProperty("user.dir");
            return new ApiInfoBuilder()
                    .title(projectName.substring(projectName.lastIndexOf("\\") + 1) + " API接口文档")
                    .contact(new Contact("jl", null, "31346337@qq.com"))
                    .version("1.0")
                    .description("API文档")
                    .build();
        }
    
    //    /**
    //     * 生成全局通用参数,按需设置
    //     */
    //    private List<RequestParameter> getGlobalRequestParameters() {
    //        List<RequestParameter> parameters = new ArrayList<>();
    //        parameters.add(new RequestParameterBuilder()
    //                .name("tfToken")
    //                .description("同飞令牌")
    //                .required(false)
    //                .in(ParameterType.HEADER)
    //                .build());
    //        return parameters;
    //    }
    
        /**
         * 生成通用响应信息
         */
        private List<Response> getGlobalResponseMessage() {
            List<Response> responseList = new ArrayList<>();
            responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
            return responseList;
        }
    
        /**
         * 设置授权信息
         */
        private List<SecurityScheme> securitySchemes() {
            ApiKey apiKey = new ApiKey("tfToken", "token", "header");
            return Collections.singletonList(apiKey);
        }
    
        /**
         * 授权信息全局应用
         */
        private List<SecurityContext> securityContexts() {
            return Collections.singletonList(
                    SecurityContext.builder()
                            .securityReferences(Collections.singletonList(new SecurityReference("tfToken", new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")})))
                            .build()
            );
        }
    }

访问swagger  [http://localhost:8080/swagger-ui/\#/][http_localhost_8080_swagger-ui]

访问knife4j  [http://localhost:8080/doc.html][http_localhost_8080_doc.html]

可以设置全局header token 及API文档导出

[http_localhost_8080_swagger-ui]: http://localhost:8080/swagger-ui/#/
[http_localhost_8080_doc.html]: http://localhost:8080/doc.html