程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

以下为你介绍的程序文档工具都可用在Linux系统上:Swagger Butler(基于 Swagger 与 Zuul 的 API 文档汇集工具)、Mirren-Swagger-API-Manager(API 接口文档管理器)、BookStackApp(使用 PHP 和 Laravel 构建文档/wiki 内容的平台)。

1、Swagger Butler(基于 Swagger 与 Zuul 的 API 文档汇集工具)

当我们构建分布式系统的时候,虽然我们可以用Swagger来方便为每个服务自动产出API文档页面。但是随着服务数量的增多,内部服务间的依赖关系的复杂度增加,每个服务开发人员要关心和查阅的文档变得越来越多。由于每个服务的文档地址可能都不一样,这使得不得不维护一个文档的索引来方便查阅,并且这个索引还需要不断的去维护更新。

那么有没有什么工具可以帮我们快速的汇集这些服务的Swagger文档呢?只需要记住一个访问地址,就可以访问所有服务的API文档?当服务增加的时候,不需要手工维护就能自动发现新服务的API文档?如果您有上面的这些问题,那么不妨看看这个项目,或许可以解决您的这些烦恼!

Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,方便查看与测试。

快速入门:

该工具的时候非常简单,先通过下面几步简单入门:

第一步:构建一个基础的Spring Boot应用

第二步:在pom.xml中引入依赖

<dependencies>

<dependency>

<groupId>com.didispace</groupId>

<artifactId>swagger-butler-core</artifactId>

<version>2.0.0</version>

</dependency>

</dependencies>

第三步:创建应用主类,增加@EnableSwaggerButler注解开启Swagger Butler功能

@EnableSwaggerButler

@SpringBootApplication

public class StaticApplication {

public static void main(String[] args) {

SpringApplication.run(StaticApplication.class);

}

}

第四步:配置文件中增加Swagger文档的地址配置

spring.application.name=swagger-butler-example-static

server.port=11000

# default config

swagger.butler.api-docs-path=/v2/api-docs

swagger.butler.swagger-version=2.0

# swagger resource

zuul.routes.user.path=/service-a/**

zuul.routes.user.url=http://localhost:10010/

swagger.butler.resources.user.name=user-service

# swagger resource

zuul.routes.product.path=/service-b/**

zuul.routes.product.url=http://localhost:10020/

swagger.butler.resources.product.name=product-service

swagger.butler.resources.product.api-docs-path=/xxx/v2/api-docs

swagger.butler.resources.product.swagger-version=2.0

上面配置了两个文档位置,由于这里还没有引入服务发现机制,所以Zuul的路由需要我们自己配置。然后在配置resource信息的时候,从1.1.0版本开始做了较大的调整,由于具体的访问路径是可以通过路由信息产生的,所以对于resource的配置信息只关注三个内容:

name:API文档在swagger中展现名称。

api-docs-path:要获取的swagger文档的具体路径,如果不配置会使用全局的。swagger.butler.api-docs-path配置,默认为/v2/api-docs。这里的配置主要用户一些特殊情况,比如服务自身设置了context-path,或者修改了swagger默认的文档路径。

swagger-version:swagger版本信息,如果不配置会使用全局的。swagger.butler.swagger-version配置,默认为2.0。

第五步:查看聚合文档

原生文档:访问http://localhost:11000/swagger-ui.html。

Example-1

增强文档:访问http://localhost:11000/doc.html。

Example-2

代码示例具体可见swagger-butler-example-static目录。

下载地址:https://gitee.com/didispace/swagger-butler

2、Mirren-Swagger-API-Manager(API 接口文档管理器)

Mirren-Swagger-API-Manager-MSAM是一个API接口文档管理器,MSAM的属性根据swagger-models-1.5.20.jar进行定义并添加了拓展属性。

MSAM以项目-接口分组-接口三个单位,项目最终生成的结果理论上兼容Swagger的Swagger UI

不过MSAM也有一个属于自己的Client-UI,可以方便的查看检索接口文档。

一些疑问:

问:为什么有Swagger了还要这个东西?

答:因为大多前后端分离的公司基本都跟本人公司一样,先接口文档然后才有项目;而Swagger是用注解现有的项目生产接口,如果用Swagger Editor写又觉得不方便管理,所以就有了这个东西.

问:为什么已经有了Swagger UI了还要搞一个MSAM Client-UI?

答:本人不喜欢Swagger UI的风格,本人的同事看Client-UI的风格已经很久了.

问:市面上已经有接口文档管理了(比如阿里的RAP等)为什么你还要自己写

答:希望能有更多的选择.

项目的结构:

项目的后台采用了大部分人熟悉的SpringBoot写(其实本人与公司已经用Vert.x一年多了,不是很喜欢Spring).

文件存储使用JDBC操作Sqlite3数据库.

Server-UI用于管理接口文档(Bootstrap).

Client-UI用于展示接口文档(Bootstrap Docs).

项目如何运行:

运行环境要求,开发环境为java 1.8.0_121,理论上java1.8以上都可以运行,如果没有java运行环境,可以看使用说明里面的免JDK教程.

项目可以在releases(发行版)里面下载已经打包好的也可以自己打包项目.

执行 mvn clean package 进行项目打包.

执行完毕后进入target/MSAM目录,该目录包含了Client-UI(展示接口文档的UI),Server-UI(管理接口的UI),config(存放接口文档的Sqlite,旧版升级可以将旧版的数据拷贝到新版.中),Mirren-Swagger-API-Manager-x.x.x.jar.

在MSAM目录中执行java -jar Mirren-Swagger-API-Manager-x.x.x.jar 启动MSAM服务,端口号默认为8686(可以自己修改,Server-UI端口的修改在js/common.js中).

进入Server-UI在浏览器中打开index.html便可以进行接口管理.

进入Client-UI在浏览器中打开index.html在顶部的输入接口文件的Json地址,或者选择本地的Json文件进行加载接口.

拓展与二次开发:

数据库里面定义了项目,接口分组,以及接口三张表,属性对应Swagger的Swagger,Tags,Operation这三个类,前端操作需要将Json类型转换为String类型.

使用说明:

第一步启动Mirren-Swagger-API-Manager.jar(start.bat / start.sh)

第二步访问Server-UI-index.html

第三步新建项目,输入项目信息后确定创建项目

第四步在项目列表中点击项目

第五步新建接口

第六步新建接口

第七步在项目信息中选择将项目转为Swagger_2.0 .Json文件并下载或在线查看获得文件路径

第八步访问Client-UI-index.html

第九步打开保存的文件,或者输入文件路径加载数据

界面展示:

Server-UI:

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

Client-UI:

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

3、BookStackApp(使用 PHP 和 Laravel 构建文档/wiki 内容的平台)

BookStack 是一个简单,自托管,易于使用的类 wiki 和在线书籍写作平台,用于组织和存储信息。

以为您的项目创建文档/维基内容。它是用 PHP 编程语言编写的,并使用 Laravel Web 框架。

功能特性:

免费开源、简易的操作界面、可搜索、可配置、支持多语言、可选的 Markdown 编辑器。

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp介绍

开发与测试:

BookStack上的所有开发当前都在master分支上完成,在发布时,master分支将合并到带有内置和精简CSS和JS的release中,然后在其版本上进行标记,以下是当前的开发要求:

Node.js v10.0+

SASS用于帮助CSS开发,并且JavaScript通过babel运行以允许编写ES6代码。这是使用webpack完成的,要运行构建任务,可以使用以下命令:

# Install NPM Dependencies

npm install

# Build assets for development

npm run build

# Build and minify assets for production

npm run production

# Build for dev (With sourcemaps) and watch for changes

npm run dev

BookStack有许多集成测试,这些测试使用Laravel的内置测试功能,该功能利用了PHPUnit。在应用程序配置中定义了一个mysql_testing数据库,PHPUnit使用该数据库。该数据库设置了全部定义为bookstack-test的数据库名称,用户名和密码。在测试之前,您将必须创建该数据库和该组凭据。

测试数据库也将需要预先迁移和播种,可以使用以下命令完成此操作:

php artisan migrate --database=mysql_testing

php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

完成后,您可以在应用程序根目录中运行php vendor/bin/phpunit来运行所有测试。

下载地址:https://gitee.com/mirrors/BookStackApp

注明

以上就是程序文档工具Swagger Butler、Mirren-Swagger-API-Manager、BookStackApp的介绍内容,这些程序文档工具都能使用在Linux操作系统中。

栏目相关文章