博客

背景：

在前后端分离的大趋势下，swagger这种强大RESTful API文档在前端开发与后端开发的联调过程中有着不可或缺的作用。由于一个微服务体系里面往往存在多个微服务，正常我们访问其中一个微服务的swagger文档的路径格式是：ip+port/doc.html。但是如果我们每看一个微服务的API文档都需要切换ip和端口，就变得比较麻烦。于是在这里小编给大家整理一份在网关zuul整合一个微服务体系下的所有swagger文档教程。

一 springboot整合swagger

首先需要在每个微服务配置swagger的相应配置。比如第一步我们需要引入swagger的依赖。

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

接下来我们需要添加配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * swagger配置类
 *
 * @author mark
 * @date 2022年12月10日 11:37:07
 */

/*@Profile({"dev", "test"}) // 仅本地测试、测试环境开启*/
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
    /*
    *
    *此方法主要配置扫描控制层的路径，需根据自己项目的控制层路径更改
    /
    @Bean
    public Docket createRestApi(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.ked.ness.controller.api")).paths(PathSelectors.any())
                .build().globalOperationParameters(setHeaderToken());

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("action-swagger").description("swagger实战").termsOfServiceUrl("")
                .version("1.0").build();
    }

    /**
     * @Description: 设置swagger文档中全局参数
     * @param
     * @Date: 2020/9/11 10:15
     * @return: java.util.List<springfox.documentation.service.Parameter>
     */

    private List<Parameter> setHeaderToken() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder userId = new ParameterBuilder();
        userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
                .required(true).build();
        pars.add(userId.build());
        return pars;
    }

}

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * webMvc配置
 *
 * @author mark
 * @date 2022年12月10日 13:33:12
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

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

有了以上配置，正常你访问该服务的IP:端口/doc.html就可以看到自动生成的swagger文档了上面第一个类的配置主要作用就是配置你的控制层扫描路径，第二个配置主要是UI的一些配置。

接下来举个配置控制层和请求体的例子。

import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author mark
 * @date 2022年12月11日 08:43:11
 */
@Slf4j
@RestController
@RequestMapping("/swagger")
public class SwaggerController {

    @PostMapping("/test")
    @ApiOperation("测试swagger功能")
    public void test(@RequestBody TestRequestDTO testRequestDTO){
      log.info("===test");
    }
}

/**
 * @author mark
 * @date 2022年12月11日 08:47:14
 */
@ApiModel("测试请求类")
@Data
public class TestRequestDTO {

    @ApiModelProperty("录像开始时间 例如：Tue Nov 30 15:52:34 CST 2021")
    private Date startTime;

    @ApiModelProperty(value = "录像结束时间 例如：Tue Nov 30 15:52:34 CST 2021",dataType = "Date")
    private Date endTime;

    @ApiModelProperty(value = "数字")
    private Integer code;

    @ApiModelProperty(value = "虽然")
    private String sor;

}

二zuul配置

zuul网关服务首先也要引入swagger依赖然后就是拿到各个微服务然后添加swaggerResource就行了，具体如下：

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!-- swagger-bootstrap-ui包使用的是旧的,新的并不稳定,有问题 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

接下来添加配置类:

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cloud.netflix.zuul.filters.ZuulProperties;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * swagger配置
 *
 * @author mark
 * @date 2022年12月12日 15:23:00
 */
@Component //交给容器管理
@Primary  //代表是Swagger主 配置
@EnableSwagger2 //启用Swagger2
public class SwaggerConfig implements SwaggerResourcesProvider {

    @Autowired
    private ZuulProperties properties;

    @Override
    public List<SwaggerResource> get() {
        //利用routeLocator动态引入微服务
        List<SwaggerResource> resources = new ArrayList<>();
        properties.getRoutes().values().stream()
                .forEach(route -> resources
                        .add(swaggerResource(route.getServiceId(), route.getPath().replace("**", "v2/api-docs"), "2.0")));
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }

}

接下来访问网关的IP：port/doc.html就可以看到接口：



关于swagger常用注解：

@Api

用在请求的类上，表示对类的说明tags=“说明该类的作用，可以在UI界面上看到的注解”。

value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”。

@ApiOperation

用在请求的方法上，说明方法的用途、作用：value=“说明方法的用途、作用”，notes=“方法的备注说明”。

@ApiImplicitParams

用在请求的方法上，表示一组参数说明

@ApiImplicitParam

用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名

value：参数的汉字说明、解释

required：参数是否必须传

paramType：参数放在哪个地方

· header –> 请求参数的获取：@RequestHeader

· query –> 请求参数的获取：@RequestParam

· path（用于restful接口）–> 请求参数的获取：@PathVariable

· body（不常用）

· form（不常用）

dataType：参数类型，默认String，其它值dataType=“Integer”

defaultValue：参数的默认值

@ApiResponses

用在请求的方法上，表示一组响应

@ApiResponse

用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400

message：信息，例如”请求参数没填好”

response：抛出异常的类

@ApiModel

用于响应类上，表示一个返回响应数据的信息

（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty

用在属性上，描述响应类的属性

作者：david161

链接：http://events.jianshu.io/p/9d8348f80ac4

来源：简书

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。