SpringBoot整合Swagger2实现分布式聚合文档

应用场景:微服务项目

项目结构如下:

 zuul为网关,

service为服务提供者,

customer为服务的调用者.

注册中心使用的是nacos

1.配置customer的swagger(service本身是一个运行正常的服务)

1.1.导入swagger的jar包 

在pom文件中加入swagger的依赖(三个项目的pom文件都加入)

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

1.2. 添加swagger的配置文件

在与controller同级的目录下新建config目录, 新建swagger的config文件SwaggerConfig, 代码如下

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import com.google.common.base.Predicates;

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;
@Configuration
@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                //.apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的package
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有ApiOperation注解的接口
                //不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("api文档的标题或者名称")
				.description("这里是关于这个api文档的简单描述")
				.version("1.0.0")// 版本号
				.build();
	}
}

项目的整体结构如下

 

配置文件application.properties

server.port=8080
spring.application.name=customer

spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848
spring.cloud.nacos.discovery.namespace=84820eac-bc61-4ba8-810d-be7e90544568

 启动项目:端口是默认的8080, 访问localhost:8080/doc.html 出现下图标识配置成功

2.配置service的swagger(customer本身也是一个运行正常的服务) 

 按照customer配置swagger的方式配置一遍service,application.properties里面修改一下端口号.即可

项目结构如下

swaggerconfig的配置也一样 

配置文件application.properties

server.port=8082
spring.application.name=menber

spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848
spring.cloud.nacos.discovery.namespace=84820eac-bc61-4ba8-810d-be7e90544568

启动项目(端口已修改8082) 访问localhost:8082/doc.html 

红色区域为我的controller 

3.网关配置swagger实现统一入口

将customer与service注册到nacos注册中心(这里不详细说)

zuul中application.properties添加如下配置

# nacos 注册中心地址
spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848
spring.cloud.nacos.discovery.namespace=84820eac-bc61-4ba8-810d-be7e90544568

# zuul转发的配置
# 对应我们service,customer注册的时候的spring.application.name的属性值
zuul.routes.customer-service.path=/customer/**
zuul.routes.customer-service.service-id=customer
zuul.routes.menber-service.path=/menber/**
zuul.routes.menber-service.service-id=menber

 在启动类平级建config包 然后新建swagger的配置类

DocumentationConfig.java

package com.example.demo.config;

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

import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {

	@Override
	public List<SwaggerResource> get() {
		List<SwaggerResource> resources = new ArrayList<SwaggerResource>();
		/**
		 * 	/customer为application里面配置的转发,
		 * 	后面部分v2/api-docs为固定写法
		 * 	2.0表示版本 可以不传任何值
		 */
		resources.add(swaggerResource("订单系统", "/customer/v2/api-docs", ""));
		resources.add(swaggerResource("支付系统", "/menber/v2/api-docs", ""));
		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;
    }
}

然后在启动类上添加启用swagger的注解

@EnableSwagger2 // Swagger的开关，表示已经启用Swagger
@EnableSwaggerBootstrapUI

启动项目(8081端口):localhost:8081/doc.html

 通过下拉框选择支付系统还是订单系统,则配置成功.

关于全局参数的配置

貌似我就这样配置,切换到另外的文档也是生效的.(保存后记得刷新一下)