0
点赞
收藏
分享

微信扫一扫

第一章 SpringBoot快速开发框架 - 集成Swagger,生成API文档

DT_M 2022-05-01 阅读 54


一、集成Swagger,生成API文档

在前后端分离的项目中,API文档是非常必要的,一个优秀的API文档能够减少前后端开发人员大量的沟通时间,提高开发效率,因此能够提供优秀的API文档也是一个后端开发人员必备的素质。

目前能够生成API的工具有很多,我们这里使用Swagger作为生成API的工具。Swagger提供了完整的管理、测试和使用API的功能,其实时性对前后端都十分的友好。

1、集成方法

(1)引入依赖

在pom.xml文件中添加Swagger依赖

<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>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

(2)在application.yml中配置Swagger是否可用

swagger:
  enable: true

(3)在工程中添加Swagger配置文件

package com.lll.framework.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author Liu Lili
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Value("${swagger.enable}")
    private boolean enableSwagger;

    /**
     * 构建api文档的详细信息函数
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("RESTful API")
                .version("1.0")
                .description("API 描述")
                .build();
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(enableSwagger).select()
                // 扫描所有有注解的api,用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();

    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2、Swagger配置说明

(1)Swagger扫描注解方法

Swagger扫描注解有两种不同的方式,具体如下:

1、指定包扫描方式

该方式会扫描指定包下面所有的controller,不管是否使用了@Api注解。

2、扫描注解方式

该方式会扫描整个工程中所有使用了@Api注解的类和@ApiOperation注解的方法,上面的示例代码就是使用了该方式。

(2)指定包扫描方式扩展

指定包扫描方式有一定的局限,如果我们的controller并没有在一个统一的包中,或者对某些controller并不想暴露出去,这个时候直接使用扫描包的方式就无法实现了。

为了满足上面的需求,我们需要对包扫描方式进行改造,改造方式为重写basePackage方法,让basePackage方法支持多包路径扫描,具体实现如下:

    /**
     * 重写basePackage方法,使能够实现多包访问
     * @return com.google.common.base.Predicate<springfox.documentation.RequestHandler>
     */
    public static Predicate<RequestHandler> basePackage(final String basePackage) {
        return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
    }

    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage)     {
        return input -> {
            // 循环判断匹配
            for (String strPackage : basePackage.split(splitor)) {
                boolean isMatch = input.getPackage().getName().startsWith(strPackage);
                if (isMatch) {
                    return true;
                }
            }
            return false;
        };
    }

    private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
        return Optional.fromNullable(input.declaringClass());
    }

(3)对swagger中的请求添加全局参数

在实际开发中,后端对外提供的接口应该是有权限验证的,需要提供token验证请求的合法性,为了能够在Swagger中对接口进行测试工作,需要给所有的接口添加全局token参数,具体实现如下:

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(enableSwagger).select()
                // 扫描所有有注解的api,用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(getParam());
    }

private List<Parameter> getParam(){
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        /**
         * Token 以及Authorization 为自定义的参数,session保存的名字是哪个就可以写成那个
         * header中的ticket参数非必填,传空也可以
         */
        ticketPar.name("Authorization").description("user ticket")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(ticketPar.build());
        return pars;
    }

3、Swagger常用注解

(1)在Controller上注解

(2)在实体类上的注解

举报

相关推荐

0 条评论