从0到1手把手搭建spring cloud alibaba 微服务大型应用框架（十五） swagger篇 : gateway 集成swagger 与 knife4j实现在线api文档并嵌入到自己项目内

背景

我们日常开发中基本都是协同开发的，当然极个别的项目整体前后端都是一个人开发的，当多人协作时，尤其是前后端人员协同开发时
必然会面临着前端需要了解后端api接口的情况，两个选择，提前设计好文档，然后维护他，让前端去参考这个文件
第二种便是通过当前代码即时去生成api，然后大家一起通过在线文档去看，这样的好处是及时性，便捷性
本文就来介绍如何微服务下通过gateway集成共通的api在线文档，这样就不需要一个服务去部署一套文档我们自定义注解实现swagger
自动集成到各个业务端并且通过knife4j 将swagger的文档更进一步美化并嵌入到我们自己的项目中

集成后效果如下：

可以看见api文档是在我们自己项目内的，而且经过knife4j的美化，api文档看起来更舒服~

swagger 简介

swagger 是一款嵌入到代码内的在线api文档生成器，详细内容不多说，大家可以到swagger 官方查看文档，点击进入官方连接

swagger api 概要与常用注解介绍

@Api 注解使用demo

@Path("/pet")
@Api(value = "/pet", description = "Operations about pets")
@Produces({"application/json", "application/xml"})
public class PetResource {...
}

@Api(value = "/sample/users", description = "gets some data from a servlet", consumes="application/json, application/xml")
public class SampleServlet extends HttpServlet {

@ApiOperation 注解使用demo

 @GET@Path("/findByStatus")@ApiOperation(value = "Finds Pets by status",notes = "Multiple status values can be provided with comma seperated strings",response = Pet.class,responseContainer = "List")public Response findPetsByStatus(...) { ... }

@ApiOperation(httpMethod = "GET", value = "Resource to get a user", response = SampleData.class, nickname="getUser")
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {...}

@ApiResponses, @ApiResponse 注解使用demo

  @ApiResponses(value = { @ApiResponse(code = 400, message = "Invalid ID supplied"),@ApiResponse(code = 404, message = "Pet not found") })public Response getPetById(...) {...}

@Authorization, @AuthorizationScope 注解使用demo

 @ApiOperation(value = "Add a new pet to the store", authorizations = {@Authorization(value="petoauth", scopes = {@AuthorizationScope(scope = "add:pet", description = "allows adding of pets")})})

@ApiParam 注解使用demo

 @Path("/{username}")@ApiOperation(value = "Updated user",notes = "This can only be done by the logged in user.")
public Response updateUser(@ApiParam(value = "name that need to be updated", required = true) @PathParam("username") String username,@ApiParam(value = "Updated user object", required = true) User user) {...}

@ApiImplicitParam, @ApiImplicitParams 注解使用demo

 @ApiImplicitParams({@ApiImplicitParam(name = "name", value = "User's name", required = true, dataType = "string", paramType = "query"),@ApiImplicitParam(name = "email", value = "User's email", required = false, dataType = "string", paramType = "query"),@ApiImplicitParam(name = "id", value = "User ID", required = true, dataType = "long", paramType = "query")})public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {...}

@ApiModel 注解使用demo

@ApiModel(value="SuperModel", discriminator = "foo", subTypes = {SubModel.class})
public class SuperModel {...}@ApiModel(value="SubModel")
public class SubModel {...}

@ApiModelProperty 注解使用demo

  @ApiModelProperty(value = "pet status in the store", allowableValues = "available,pending,sold")public String getStatus() {return status;}

knife4j 简介

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j
更名后主要专注的方面前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分提供更多灵活的中间件方案\工具

集成swagger 与 knife4j 详细配置与代码

项目依赖结构图

gateway服务集成详细详细配置与代码

这里gateway 是独立部署的，是由于老版本漏洞问题，具体原因以及如何独立部署请参考《从0到1 手把手搭建spring cloud alibaba 微服务大型应用框架（六）(gateway篇)spring cloud gateway 远程漏洞原因升級到3.1.1完整配置》

代码结构

完整配置和代码

knife4j 依赖

        <knife4j.version>2.0.8</knife4j.version>

 <!--knife4j 依赖--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-ui</artifactId><version>${knife4j.version}</version></dependency>

MiniCloudSwaggerHandler.java

@RestController
public class MiniCloudSwaggerHandler {@Autowired(required = false)private SecurityConfiguration securityConfiguration;@Autowired(required = false)private UiConfiguration uiConfiguration;private final SwaggerResourcesProvider swaggerResources;@Autowiredpublic MiniCloudSwaggerHandler(SwaggerResourcesProvider swaggerResources) {this.swaggerResources = swaggerResources;}@GetMapping("/swagger-resources/configuration/security")public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {return Mono.just(new ResponseEntity<>(Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));}@GetMapping("/swagger-resources/configuration/ui")public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {return Mono.just(new ResponseEntity<>(Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));}@GetMapping("/swagger-resources")public Mono<ResponseEntity> swaggerResources() {return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));}
}

MiniCloudSwaggerHeaderFilter.java

public class MiniCloudSwaggerHeaderFilter extends AbstractGatewayFilterFactory {private static final String HEADER_NAME = "X-Forwarded-Prefix";private static final String URI = "/v2/api-docs";@Overridepublic GatewayFilter apply(Object config) {return (exchange, chain) -> {ServerHttpRequest request = exchange.getRequest();String path = request.getURI().getPath();if (!StringUtils.endsWithIgnoreCase(path,URI )) {return chain.filter(exchange);}String basePath = path.substring(0, path.lastIndexOf(URI));ServerHttpRequest newRequest = request.mutate().header(HEADER_NAME, basePath).build();ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();return chain.filter(newExchange);};}
}

MiniCloudSwaggerResourceConfig.java

@Slf4j
@Component
@AllArgsConstructor
public class MiniCloudSwaggerResourceConfig implements SwaggerResourcesProvider {private final RouteLocator routeLocator;private final GatewayProperties gatewayProperties;@Overridepublic List<SwaggerResource> get() {List<SwaggerResource> resources = new ArrayList<>();List<String> routes = new ArrayList<>();routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {route.getPredicates().stream().filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName())).forEach(predicateDefinition -> resources.add(swaggerResource(route.getId(),predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0").replace("**", "v2/api-docs"))));});return resources;}private SwaggerResource swaggerResource(String name, String location) {log.info("name:{},location:{}",name,location);SwaggerResource swaggerResource = new SwaggerResource();swaggerResource.setName(name);swaggerResource.setLocation(location);swaggerResource.setSwaggerVersion("2.0");return swaggerResource;}
}

添加 swagger 共通module 并实现自定义注解

代码结构

完整代码

父级pom添加

 <swagger.version>1.5.21</swagger.version><knife4j.version>2.0.8</knife4j.version>

   <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>${swagger.version}</version></dependency>

mini-cloud-common-swagger pom 添加

 <dependencies><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-micro-spring-boot-starter</artifactId></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId></dependency><!--web 模块--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency></dependencies>

EnableMiniCloudSwagger.java

@Documented
@Inherited
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Import(MiniCloudSwaggerConfiguration.class)
public @interface EnableMiniCloudSwagger {}

MiniCloudSwaggerConfiguration.java


@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class MiniCloudSwaggerConfiguration {@Bean(value = "userApi")@Order(value = 1)public Docket groupRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(groupApiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.minicloud")).paths(PathSelectors.any()).build();}private ApiInfo groupApiInfo(){return new ApiInfoBuilder().title("mini-cloud api list").description("<div style='font-size:14px;color:red;'>MINI-CLOUD APIS</div>").termsOfServiceUrl("http://minicloud.com/").contact("alan.wang").version("1.0").build();}
}

业务端添加swagger注解并集成swagger共通demo

基于上面封装的EnableMiniCloudSwagger注解自动引入，本篇使用upms服务做例子说明

pom 依赖引入

auth 认证服务放开对swagger 文档的请求拦截

由于我们是基于认证服务的，所以需要放开对这些在线文档的请求权限认证

vue 前端嵌入文档

启动查看演示效果

总结

我们是基于mini-cloud 集成的，大家完全可以根据自己的框架进行集成，核心点在于knife4j 以及swagger 的依赖与这几个类，大家可以直接拷贝我文中的依赖和类拿到自己项目中使用即可

从0到1手把手搭建spring cloud alibaba 微服务大型应用框架（十五） swagger篇 : gateway 集成swagger 与 knife4j实现在线api文档并嵌入到自己项目内相关推荐

从0到1 手把手搭建spring cloud alibaba 微服务大型应用框架（三） (mini-cloud) 搭建认证服务（认证/资源分离版） oauth2.0 (中)
本文承接上文<从0到1 手把手搭建spring cloud alibaba 微服务大型应用框架(三) (mini-cloud) 搭建认证服务(认证/资源分离版) oauth2.0 (上)> ...
从0到1带大家把手搭建spring cloud alibaba 微服务大型应用框架（八） saas平台篇-解决不同租户针定制化开发问题 -完整代码以及案例方案(1)
问题描述平台越做越大到多租户时,经常会遇见一种情况,就是某些用户希望自己的功能是定制化的,有可能是完全的新功能,也有可能压根就是同样的功能但是A和B两个用户的实现前后台展示和逻辑就压根不同不可能在 ...
《深入理解 Spring Cloud 与微服务构建》第十五章微服务监控 Spring Boot Admin
<深入理解 Spring Cloud 与微服务构建>第十五章微服务监控 Spring Boot Admin 文章目录 <深入理解 Spring Cloud 与微服务构建>第十 ...
防止内卷和被潜规则，Spring Cloud Alibaba微服务架构实战派（上下册）｜35岁程序员那些事
目录 1 写书缘由 2 本书上册核心内容 2.1 Spring Cloud Alibaba基础实战 2.1.1 主要内容 2.1.2 MyBatis-Plus实现多租户架构的核心原理 2.2 分布式服 ...
《深入理解 Spring Cloud 与微服务构建》第十八章使用 Spring Security OAuth2 和 JWT 保护微服务系统
<深入理解 Spring Cloud 与微服务构建>第十八章使用 Spring Security OAuth2 和 JWT 保护微服务系统文章目录 <深入理解 Spring Cl ...
《深入理解 Spring Cloud 与微服务构建》第十四章服务链路追踪 Spring Cloud Sleuth
<深入理解 Spring Cloud 与微服务构建>第十四章服务链路追踪 Spring Cloud Sleuth 文章目录 <深入理解 Spring Cloud 与微服务构建> ...
《深入理解 Spring Cloud 与微服务构建》第十六章 Spring Boot Security 详解
<深入理解 Spring Cloud 与微服务构建>第十六章 Spring Boot Security 详解文章目录 <深入理解 Spring Cloud 与微服务构建>第十 ...
《深入理解 Spring Cloud 与微服务构建》第十二章服务注册和发现 Consul
<深入理解 Spring Cloud 与微服务构建>第十二章服务注册和发现 Consul 文章目录 <深入理解 Spring Cloud 与微服务构建>第十二章服务注册和发 ...
Spring Cloud Alibaba 微服务开发实践
作者:禅与计算机程序设计艺术 1.简介 Spring Cloud Alibaba 是阿里巴巴开源的基于 Spring Cloud 的微服务框架.该项目从最初孵化到现在已经历经十多年的发展,得到了广泛的 ...

从0到1手把手搭建spring cloud alibaba 微服务大型应用框架（十五） swagger篇 : gateway 集成swagger 与 knife4j实现在线api文档并嵌入到自己项目内

背景

集成后效果如下：

swagger 简介

swagger api 概要与常用注解介绍

@Api 注解使用demo

@ApiOperation 注解使用demo

@ApiResponses, @ApiResponse 注解使用demo

@Authorization, @AuthorizationScope 注解使用demo

@ApiParam 注解使用demo

@ApiImplicitParam, @ApiImplicitParams 注解使用demo

@ApiModel 注解使用demo

@ApiModelProperty 注解使用demo

knife4j 简介

集成swagger 与 knife4j 详细配置与代码

项目依赖结构图

gateway服务集成详细详细配置与代码

代码结构

完整配置和代码

添加 swagger 共通module 并实现自定义注解

代码结构

完整代码

业务端添加swagger注解并集成swagger共通demo

auth 认证服务放开对swagger 文档的请求拦截

vue 前端嵌入文档

启动查看演示效果

总结

从0到1手把手搭建spring cloud alibaba 微服务大型应用框架（十五） swagger篇 : gateway 集成swagger 与 knife4j实现在线api文档并嵌入到自己项目内相关推荐

最新文章

热门文章