配置详解
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–举例说明
原文链接:https://blog.csdn.net/guozhangjie1992/article/details/95676729