基于springboot的⽂档管理
简介
本篇⽂章将阐述如何通过使⽤我开发Parliament，与Swagger、Keyhole Software提供的⼯具，搭建⼀套⾃动发布、集中管理的API⽂档中⼼。
springboot架构图背景介绍
Spring Boot与Sping Cloud等项⽬为我们搭建微服务架构提供了很⼤的便利。但是微服务架构的劣势之⼀就是增加了治理的复杂度。
众所周知，微服务架构中的各个应⽤是独⽴开发、部署的。当微服务数量到达⼀定的数量后，集中管理API⽂档的难度越来越⼤。
为了减轻⽂档压⼒，很多Spring Boot项⽬集利⽤Swagger⾃动⽣成API描述页⾯。然⽽Swagger并没有解决API集中管控的问题，各个团队必须清楚的知道其他团队的Swagger页⾯地址，这势必完成了维护成本。这也是Parliament项⽬初衷。
解决⽅案
我开发了⼀个简单的API⽂档中⼼服务器Parliament。Parliament集成了Swagger UI，⽤于显⽰和调试API。
API信息发布采⽤的是Keyhole Software开发的khs-spring-boot-publish-swagger-starter。需要注意的是原始的khs-spring-boot-publish-swagger-starter存在⼏个bug，请暂时使⽤
我提供的版本。
背后的逻辑是：
1. 由Swagger2负责⽣成API描述，
2. 当Spring Boot应⽤每次启动时，通过khs-spring-boot-publish-swagger-starter将API描述发送到Parliament服务器。
3. Parliament服务器存储并整理API描述，并提供UI展⽰给各个团队开发⼈员。
这样我们就拥有了⼀个集中的、⾃动化的API⽂档中⼼。
开始搭建
在部署Parliament之前，我们需要先安装MongoDB。关于如何安装、配置MongoDB不在此⽂章范围。安装好MongoDB后，进⾏如下步骤。
I. 部署Parliament
$git clone github/burnettzhong/parliament.git
$cd parliament
修改application.properties，配置数据源, 请将根据实际的MongoDB信息修改：
db.host = {MongoDB address}
db.database = {MongoDB database name}
db.port = {MongoDB port}
构建并启动Parliament:
$mvn package && java -jar target/Parliament-1.0.0.jar
II. 让Spring Boot应⽤发布API信息
这⾥我们需要加⼊两个依赖库，⼀个是SpringFox的Swagger2，另⼀个是khs-spring-boot-publish-swagger-startera。
注意：请不要使⽤来⾃Keyhole Software的khs-spring-boot-publish-swagger-starter，其中有两个bug。只有他们合并我们pull request，才可以直接使⽤。
1. 在Keyhole Software在Maven公共库中更新之前，我们需要⼿动安装我的版本(1.0.2)到本地Maven库中:
git clone github/burnettzhong/khs-spring-boot-publish-swagger-starter
cd khs-spring-boot-publish-swagger-starter
mvn clean install
2. 在Spring Boot应⽤中增加Swagger2和khs-spring-boot-publish-swagger-starter依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>com.keyholesoftware</groupId>
<artifactId>khs-spring-boot-publish-swagger-starter</artifactId>
<version>1.0.2</version>
</dependency>
3. 在l或application.properties中配置Parliament地址：
swagger:
publish:
publish-url: {Parliament server address}/swagger/publish/
swagger-url: 127.0.0.1:${server.port}/v2/api-docs
这⾥有两个地址，publish-url是我们的Parliament部署地址,；swagger-url为获取API描述地址，⼀般来讲都是本应⽤地址。1. 最后通过注解配置Spring Boot应⽤：
@EnableSwagger2
@PublishSwagger
public class ServiceApplication {
...
}
@EnableSwagger2启⽤Swagger2⽣成API描述，@PublishSwagger让应⽤在启动的时候将API描述JSON发布到Parliament。关于API描述的配置，Swagger2提供了很丰富的功能，请参考。
后记
1. 如果需要，可以将Parliament作为⼀个微服务注册到Euraka或者Zookeeper中。
2. 因为Parliament主要是在内⽹使⽤，⽬前没有进⾏安全验证。未来会引⼊对应⽤的认证，和⽤户管理。
3. 未来Parliament还将增加API使⽤统计的功能，完善整体API治理。
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论