温州微网站制作公司哪家好,北京简盟产品设计有限公司,百度如何创建网站,平面设计学院Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用#xff0c;增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起#xff0c;方便查看与测试。
项目地址
Github#xff1a;https://github.com/dyc87112/…Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起方便查看与测试。
项目地址
Githubhttps://github.com/dyc87112/swagger-butlerGiteehttps://gitee.com/didispace/swagger-butler
快速入门
该工具的时候非常简单先通过下面几步简单入门
第一步构建一个基础的Spring Boot应用
如您还不知道如何创建Spring Boot应用可以先阅读本篇入门文章
第二步在pom.xml中引入依赖
parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version1.5.10.RELEASE/version/parentdependencies dependency groupIdcom.didispace/groupId artifactIdswagger-butler-core/artifactId version1.1.0/version /dependency/dependencies第三步创建应用主类增加EnableSwaggerButler注解开启Swagger Butler功能
EnableSwaggerButlerSpringBootApplicationpublic class StaticApplication { public static void main(String[] args) { SpringApplication.run(StaticApplication.class); }}第四步配置文件中增加Swagger文档的地址配置
spring.application.nameswagger-butler-example-staticserver.port11000# default configswagger.butler.api-docs-path/v2/api-docsswagger.butler.swagger-version2.0# swagger resourcezuul.routes.user.path/service-a/**zuul.routes.user.urlhttp://localhost:10010/swagger.butler.resources.user.nameuser-service# swagger resourcezuul.routes.product.path/service-b/**zuul.routes.product.urlhttp://localhost:10020/swagger.butler.resources.product.nameproduct-serviceswagger.butler.resources.product.api-docs-path/xxx/v2/api-docsswagger.butler.resources.product.swagger-version2.0上面配置了两个文档位置由于这里还没有引入服务发现机制所以Zuul的路由需要我们自己配置。然后在配置resource信息的时候从1.1.0版本开始做了较大的调整由于具体的访问路径是可以通过路由信息产生的所以对于resource的配置信息只关注三个内容
nameAPI文档在swagger中展现名称api-docs-path要获取的swagger文档的具体路径如果不配置会使用全局的swagger.butler.api-docs-path配置默认为/v2/api-docs。这里的配置主要用户一些特殊情况比如服务自身设置了context-path或者修改了swagger默认的文档路径swagger-versionswagger版本信息如果不配置会使用全局的swagger.butler.swagger-version配置默认为2.0。
第五步访问http://localhost:11000/swagger-ui.html 代码示例具体可见swagger-butler-example-static目录 Zuul的路由与SwaggerResources配置之间的关系
如上示例中route-name展示了Zuul的路由名称与SwaggerResources配置之间的关联关系
zuul.routes.route-name.path/service-b/**zuul.routes.route-name.urlhttp://localhost:10020/swagger.butler.resources.route-name.nameproduct-serviceswagger.butler.resources.route-name.api-docs-path/xxx/v2/api-docsswagger.butler.resources.route-name.swagger-version2.0注意在没有使用自动配置或整合服务治理的时候要生成Swagger文档的时候resources信息中的name属性是必须配置的api-docs-path和swagger-version不配置的时候会使用默认的全局配置 全局配置
对于Swagger文档获取的全局配置内容目前主要包含下面几个参数
swagger.butler.api-docs-path/v2/api-docsswagger.butler.swagger-version2.0使用Zuul中的路由自动配置新特性
在快速入门示例中我们配置了两个路由信息同时为这两个路由信息配置了对应的Swagger信息来获取API文档详情从1.1.0版本开始增加了几个通过Zuul的路由配置来自动生成文档信息的参数这样可以减少快速入门示例中那些繁琐的配置。对于快速入门例子我们可以做如下改造
# swagger resourcezuul.routes.user.path/service-a/**zuul.routes.user.urlhttp://localhost:10010/# swagger resourcezuul.routes.product.path/service-b/**zuul.routes.product.urlhttp://localhost:10020/# use zuul routes generate swagger resourcesswagger.butler.auto-generate-from-zuul-routestrue在设置了swagger.butler.auto-generate-from-zuul-routestrue之后会默认的根据zuul中的路由信息来生成SwaggerResource。其中原来resource中的name会使用zuul route的名称比如上面的user和product而api-docs-path和swagger-version配置会使用默认的全局配置。如果resource中的三个参数有特殊情况要处理可以采用快速入门中的配置方式来特别指定即可。
忽略某些路由生成
# swagger resourcezuul.routes.user.path/service-a/**zuul.routes.user.urlhttp://localhost:10010/# swagger resourcezuul.routes.product.path/service-b/**zuul.routes.product.urlhttp://localhost:10020/# use zuul routes generate swagger resourcesswagger.butler.auto-generate-from-zuul-routestrueswagger.butler.ignore-routesproduct如上示例通过swagger.butler.ignore-routes参数可以从当前配置的路由信息中排除某些路由内容不生成文档配置内容为zuul中的路由名称配置多个的时候使用,分割。 注意swagger.butler.ignore-routes和swagger.butler.generate-routes不能同时配置。这两个参数都不配置的时候默认为zuul中的所有路由生成文档。 指定某些路由生成
# swagger resourcezuul.routes.user.path/service-a/**zuul.routes.user.urlhttp://localhost:10010/# swagger resourcezuul.routes.product.path/service-b/**zuul.routes.product.urlhttp://localhost:10020/# use zuul routes generate swagger resourcesswagger.butler.auto-generate-from-zuul-routestrueswagger.butler.generate-routesproduct如上示例通过swagger.butler.generate-routes参数可以从当前配置的路由信息中指定某些路由内容生成文档配置内容为zuul中的路由名称配置多个的时候使用,分割。 注意swagger.butler.ignore-routes和swagger.butler.generate-routes不能同时配置。这两个参数都不配置的时候默认为zuul中的所有路由生成文档。 与服务治理整合
与eureka整合
在整合eureka获取所有该注册中心下的API文档时只需要在上面工程的基础上增加下面的配置
第一步pom.xml中增加eureka依赖比如
dependencies dependency groupIdcom.didispace/groupId artifactIdswagger-butler-core/artifactId version1.1.0/version /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-eureka/artifactId version1.3.2.RELEASE/version /dependency/dependencies第二步应用主类增加EnableDiscoveryClient比如
EnableDiscoveryClientEnableSwaggerButlerSpringBootApplicationpublic class EurekaApplication { public static void main(String[] args) { SpringApplication.run(EurekaApplication.class); }}第三步修改配置文件增加eureka的配置比如
spring.application.nameswagger-butler-example-eurekaserver.port11001eureka.client.service-url.defaultZonehttp://eureka.didispace.com/eureka/swagger.butler.auto-generate-from-zuul-routestrueswagger.butler.generate-routesswagger-service-a, swagger-service-bswagger.butler.resources.swagger-service-b.api-docs-path/xxx/v2/api-docs由于整合了eureka之后zuul会默认为所有注册服务创建路由配置默认的路由名为服务名所以只需要通过swagger.butler.auto-generate-from-zuul-routestrue参数开启根据路由信息生成文档配置的功能配合swagger.butler.ignore-routes和swagger.butler.generate-routes参数就可以指定要生成的范围了如果某些服务需要特殊配置也可以通过wagger.butler.resources.*的配置来覆盖默认设置比如上面的swagger.butler.resources.swagger-service-b.api-docs-path/xxx/v2/api-docs指定了swagger-service-b服务获取swagger文档的请求路径为/xxx/v2/api-docs。 代码示例具体可见swagger-butler-example-eureka目录 与consul整合
在整合eureka获取所有该注册中心下的API文档时只需要在上面工程的基础上增加下面的配置
第一步pom.xml中增加consul依赖比如
dependencies dependency groupIdcom.didispace/groupId artifactIdswagger-butler-core/artifactId version1.1.0/version /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-consul-discovery/artifactId version1.3.2.RELEASE/version /dependency/dependencies第二步应用主类增加EnableDiscoveryClient比如
EnableDiscoveryClientEnableSwaggerButlerSpringBootApplicationpublic class EurekaApplication { public static void main(String[] args) { SpringApplication.run(EurekaApplication.class); }}第三步配置文件中增加eureka的配置比如
spring.application.nameswagger-butler-example-consulserver.port11002spring.cloud.consul.hostlocalhostspring.cloud.consul.port8500swagger.butler.auto-generate-from-zuul-routestrueswagger.butler.generate-routesswagger-service-a, swagger-service-bswagger.butler.resources.swagger-service-b.api-docs-path/xxx/v2/api-docs这里除了consul自身的配置之外其他内容与整合eureka时候的是一样的。 代码示例具体可见swagger-butler-example-consul目录 贡献者
程序猿DD
公众号
