配置详解

1、接口服务工程的pom文件中引入swagger2

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2、注入swagger配置

@Configuration

@EnableSwagger2

public class SwaggerConfig {



    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.xx.xx"))

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

                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                .paths(PathSelectors.any())

                .build();

    }



    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("example系统接口文档")

                .description("这是系统接口文档说明")

                .contact(new Contact("XXXX", "", ""))

                .version("1.0")

                .build();

    }



    @Bean

    UiConfiguration uiConfig() {

        return new UiConfiguration(null, "list", "alpha", "schema",

                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);

    }

}

3、在接口（controller）添加swagger注解

详细注解下边会做详细解释

4、启动类加注解

@EnableSwagger2

单个项目配置swagger2已经完成，访问http://127.0.0.1:8081/rest/swagger-ui.html

5、网关工程引入swagger的pom（同1）

6、网关工程注入swagger2配置

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("系统集成api")
                .description("系统接口集成文档说明")
                .contact(new Contact("XXXX", "", ""))
                .version("1.0")
                .build();
    }
}

7、网关集成接口工程swagger2（建议使用第二种）

网关搜索配置

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("Hello接口", "/XX-api/aaa/rest/v2/api-docs", "1.0"));
        resources.add(swaggerResource("检查系统接口", "/XX-api/rest/v2/api-docs", "1.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;
    }

}

2、网关zuul配置文件配置，自动搜索（需同步配置文件）

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {

    private final RouteLocator routeLocator;

    public DocumentationConfig(RouteLocator routeLocator) {
        this.routeLocator = routeLocator;
    }

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<Route> routes = routeLocator.getRoutes();
        //在这里遍历的时候，可以排除掉敏感微服务的路由
        routes.forEach(route -> resources.add(swaggerResource(route.getId(), route.getFullPath().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;
    }
}

8、zuul配置

配置后，swagger2会根据routes配置去找对应的v2/api-docs。

当strip-prefix=true的时候（http://127.0.0.1:8040/api/user/list -> http://192.168.1.100:8080/user/list）

当strip-prefix=false的时候（http://127.0.0.1: 8040/api/user/list -> http://192.168.1.100:8080/api/user/list）

strip-prefix会影响到查找接口工程swagger文件，注意和上第7点中route.getFullPath().replace("**", "v2/api-docs"),"2.0")));配合。

9、网关启动类加注解

@EnableSwagger2

访问：http://127.0.0.1:8040/swagger-ui.html

至此，zuul集成swagger2完毕。

常用注解

- @Api()用于类；
表示标识这个类是swagger的资源
- @ApiOperation()用于方法；
表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体参数说明：
@Api()
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list

@ApiOperation() 用于方法；表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

@ApiModel()用于类；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

spring cloud集成swagger2(监听多个项目)