springboot集成swagger2

最新推荐文章于 2024-11-06 21:15:07 发布

情丝千万丈

最新推荐文章于 2024-11-06 21:15:07 发布

阅读量126

点赞数

分类专栏： swagger2 java 文章标签： spring boot

原文链接：https://blog.csdn.net/weixin_44146379/java/article/details/104825273

版权

java 同时被 2 个专栏收录

17 篇文章 0 订阅

订阅专栏

swagger2

1 篇文章 0 订阅

订阅专栏

springboot集成swagger2
没接触swagger2之前，我们常规的做法就是创建一份 RESTful API 文档来提供给前端（我常用的是yapi，当然还有好多在线文档。。。）缺点这里就不再说了，今天主要说一下swagger的使用！

swagger2的优点：

1.使用简单，方便上手。
2.支持在线接口测试，不依赖第三方工具；
3.接口文档在线自动生成，文档随接口变动实时更新，节省维护成本；

springboot集成swagger2

1.pom.xml中进入maven依赖：

<!--swagger2-->
        <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>
		<dependency>           
            <groupId>io.swagger</groupId>            
              <artifactId>swagger-annotations</artifactId>           
                <version>1.5.21</version>       
       </dependency>        
        <dependency>            
            <groupId>io.swagger</groupId>            
            <artifactId>swagger-models</artifactId>            
           <version>1.5.21</version>        
       </dependency>

之前使用2.7.2版本，会有一个问题：SpringBoot集成swagger（之后正常使用，后面优化增加@Api注解，tags用的中文描述，之后发现无法展开只能用右边的集体展开后收起按钮操作。

2.创建swagger2配置类：

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 *  swagger-ui配置类
 *    访问地址 http://localhost:1333/swagger-ui.html
 *   （踩坑：1.如使用swagger，启动时需在启动类加上@EnableSwagger2
 *          2.使用@Value()获取配置文件值时，类上需加@Component，标明这个类需要在spring管理之下@Value才会生效）
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger2.enable}")
    private boolean enable;
    @Bean
    public Docket createRestApi() {
        List<Parameter> parameters = new ArrayList<>();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        parameterBuilder.name("Access-Token").description("swagger测试调用（模拟用户进行认证凭证）").modelRef(new ModelRef("String"))
                .parameterType("header").required(false);
        parameters.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
        //为当前包路径[RequestHandlerSelectors.any()所有的controller，RequestHandlerSelectors.basePackage()指定包下的controller]
               // .apis(RequestHandlerSelectors.any())        .apis(RequestHandlerSelectors.basePackage("com.shiro.springbootshiro.controller"))
                .paths(PathSelectors.any())
                .build()
                .enable(enable)//设置开关
                .globalOperationParameters(parameters);//加入token头
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //大标题
                .title("springboot+shiro+redis+swagger2.0接口文档")
                //描述
                .description("SwaggerApi接口文档")
                //版本
                .version("1.0")
                .contact(new Contact("姓名","test","xx@qq.com"))
                .build();
    }

}

3.允许访问Swagger ui静态页面：

/**
 * Created by xf on 2020/03/12.
 * SpringBoot之整合Swagger2不显示文档页面问题处理：
 * 这个问题是资源映射不到导致，swagger-ui.html是在jar包里面，SpringBoot自动配置也找不到这个页面。
 */
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
 
    /**
     * 配置swagger-ui 访问静态资源
     * */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        /**
         * SpringBoot自动配置本身并不会把/swagger-ui.html
         * 这个路径映射到对应的目录META-INF/resources/下面
         * 采用WebMvcConfigurerAdapter将swagger的静态文件进行发布;
         */
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        //将所有/static/** 访问都映射到classpath:/static/ 目录下
        registry.addResourceHandler("/static/**").addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX +"/static/");
        super.addResourceHandlers(registry);
    }
}