Swagger 3.0框架搭建及简单示例

Posted 2021-08-27 Elon.Yang

在基于Spring boot搭建的Java微服务上集成Swagger 3.0方便Restful接口调测。由于第三方组件升级和业务连续性原因，原来的Swagger 2.0需要升级到Swagger 3.0。

一. 引入Swagger 3.0依赖的包

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>

二、增加Swagger配置初始化代码

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ExampleBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;


@Configuration
@EnableOpenApi
public class Swagger3Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(getApiInfo())
                .globalRequestParameters(buildGlobalHeaderParam());
    }

    private ApiInfo getApiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder().title("Swagger 3.0")
                .description("Swagger 3.0配置Demo")
                .termsOfServiceUrl("https://blog.csdn.net/ylforever")
                .version("1.0")
                .build();
        return apiInfo;
    }

    /**
     * 构建公共参数
     *
     * @return elon
     */
    private List<RequestParameter> buildGlobalHeaderParam() {
        List<RequestParameter> globalParamList = new ArrayList<>();
        RequestParameter account = new RequestParameterBuilder().name("account")
                .in(ParameterType.HEADER)
                .example(new ExampleBuilder().value("zh1234").build())
                .build();
        globalParamList.add(account);

        RequestParameter name = new RequestParameterBuilder().name("name")
                .in(ParameterType.HEADER)
                .example(new ExampleBuilder().value("zhang san").build())
                .build();
        globalParamList.add(name);

        return globalParamList;
    }
}

（1）使用注解扫描API，代替指定controller文件路径的方式更加灵活。也更方便抽取成公共组件。

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

（2）初始化公共参数。项目中有约定大部分接口调用时都需要传递的参数，在初始化时统一设定。

.globalRequestParameters(buildGlobalHeaderParam());

说明：在初始化全局公共参数的代码中指定了默认值，但是没有生效(在Swagger 2.0中是可以的)。这好像是Swagger 3.0的一个问题，大家如知道怎样设置默认参数的话，望不吝赐教。这个不影响使用，只是每次用的时候都需要手工输入参数。

.example(new ExampleBuilder().value("zh1234").build())

三. 简单样例代码

（1）. controller接口代码

import javax.servlet.http.HttpServletRequest;

@RestController
@RequestMapping("/v1/swagger3")
@Api(tags = "Swagger3.0测试服务")
public class Swagger3Controller {
    private static final Logger LOGGER = LogManager.getLogger(Swagger3Controller.class);

    @PostMapping("/metod")
    @ApiOperation(value = "Swagger3.0测试接口")
    public String swagger3Method(@RequestBody String body) {
        HttpServletRequest request = ((ServletRequestAttributes)RequestContextHolder.getRequestAttributes())
                .getRequest();

        String account = request.getHeader("account");
        String name = request.getHeader("name");
        LOGGER.info("account:{}|name:{}", account, name);

        return body;
    }
}

（2）swagger访问页面


注意：Swagger2.0升级到Swagger3.0后访问地址有变化。后缀由swagger-ui.html改为swagger-ui/index.html

样例代码github地址： https://github.com/ylforever/elon-swagger3