SpringBoot 集成Swagger2 管理API接口文档

爱被打了一巴掌 2023-06-29 14:58 19阅读 0赞

Springboot项目中接口管理文档Swagger2的使用

1 添加依赖，本人使用的maven，必须建立springboot web项目。

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

2 添加Swagger 配置

package com.cqut.archive.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    import java.util.List;
    
    /**
     * @author :zoboy
     * @Description:
     * @ Date: Created in 2020-01-10 10:54
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
            ParameterBuilder ticketPar = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<Parameter>();
            ticketPar.name("Authorization").description("user authorization")
                    .modelRef(new ModelRef("string")).parameterType("header")
                    .required(false).build(); //header中的ticket参数非必填，传空也可以
            pars.add(ticketPar.build());    //根据每个方法名也知道当前方法在设置什么参数
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .pathMapping("/")
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.cqut.archive.controller"))
                    .paths(PathSelectors.any())
                    .build().apiInfo(new ApiInfoBuilder()
                            .title("Archive")
                            .version("1.0")
                            .build()).globalOperationParameters(pars);
        }
    
        //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
                    .title("XXX系统 API")
                    //创建人
                    .contact("XXX系统")
                    //版本号
                    .version("1.0.0")
                    //描述
                    .description("XXX系统")
                    .build();
        }
    }

3 启动项目，浏览器访问：[http://localhost:7100/swagger-ui.html\#/][http_localhost_7100_swagger-ui.html]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTEwNTE5MTI_size_16_color_FFFFFF_t_70][]

4 如果springboot项目有  WebMvcConfigurerAdapter 拦截，需要给swagger放行：

@Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/**").addResourceLocations("file:" + baseRootDir);
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
            super.addResourceHandlers(registry);
        }

public void addInterceptors(InterceptorRegistry registry) {
            InterceptorRegistration addInterceptor = registry.addInterceptor(getSecurityInterceptor());
            // 排除配置
            addInterceptor.excludePathPatterns("/error");
            addInterceptor.excludePathPatterns("/file/**");
            addInterceptor.excludePathPatterns("/swagger-ui.html/**");
            addInterceptor.excludePathPatterns("/webjars/**");
            addInterceptor.excludePathPatterns("/v2/**");
            addInterceptor.excludePathPatterns("/swagger-resources/**");
            addInterceptor.excludePathPatterns("/api/noAuthor/**");
            // 拦截配置
            addInterceptor.addPathPatterns("/**");
        }

这样既可通过。

[http_localhost_7100_swagger-ui.html]: http://localhost:7100/swagger-ui.html#/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTEwNTE5MTI_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200113111553797.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3UwMTEwNTE5MTI=,size_16,color_FFFFFF,t_70