README

API 蓝图渲染器。

您可以将 API 蓝图文档与请求/响应（text-plain、json、xml 等）文件分割，并将其包含在主文档中，以便于维护。

如果您需要用这些 API 蓝图文档加载模拟服务器，可以将它们处理以在单个文件中渲染所有内容（包括请求/响应文件），然后在模拟服务器（如 drakov 或类似工具）中加载此文件。

将从该单个文件生成 HTML 文档。

安装

此工具使用 markdown-pp 和 aglio 在 API 蓝图文档中包含请求/响应文件并生成 HTML 文档。

您可以通过执行 shell 脚本来安装 MarkdownPP 和 Aglio

./install.sh

或者按以下步骤安装

安装 markdown-pp

pip install MarkdownPP

安装 aglio

npm install -g aglio

使用 composer 安装一些依赖项

composer install

用法

示例 apib 文件

+ Request OK (application/json;charset=UTF-8)

    + Body

            {
                "checkIn": "YYY-mm-dd",
                "checkOut": "YYY-mm-dd",
                "occupancy": "A",
                "hotelCode": "A",
                "locationCode": "A"
            }

+ Response 200 (application/xml;charset=UTF-8)

    + Body

<!-- include markdown-pp (without spaces before) -->
!INCLUDE "Response/a.xml"

文件 Response\a.xml 将包含

<csw:GetRecordsResponse xmlns:csw="http://www.opengis.net/cat/csw" xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:dct="http://www.purl.org/dc/terms/" xsi:schemaLocation="http://www.opengis.net/cat/csw https://:8888/SpatialWS-SpatialWS-context-root/cswservlet?recordTypeId=1 " version="2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <csw:RequestId>4</csw:RequestId>
   <csw:SearchStatus status="complete"/>
   <csw:SearchResults recordSchema="http://www.opengis.net/cat/csw" numberOfRecordsMatched="1" numberOfRecordsReturned="1" nextRecord="0" expires="2007-02-09T16:32:35.29Z">
      <csw:Record xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:ows="http://www.opengis.net/ows" xmlns:dct="http://www.purl.org/dc/terms/">
         <dc:contributor xmlns:dc="http://www.purl.org/dc/elements/1.1/" scheme="http://www.example.com">Raja</dc:contributor>
         <dc:identifier xmlns:dc="http://www.purl.org/dc/elements/1.1/">REC-1</dc:identifier>
      </csw:Record>
   </csw:SearchResults>
</csw:GetRecordsResponse>

如果您从该工具执行命令 ``./bin/split-blue c``，您将生成两个文件

• Build/out.apib（包含 a.xml 文件的内容）
• Build/out.html（包含 a.xml 文件内容的 API 文档的 HTML 文档）

Build/out.apib 文件的内容将是

+ Request OK (application/json;charset=UTF-8)

    + Body

            {
                "checkIn": "YYY-mm-dd",
                "checkOut": "YYY-mm-dd",
                "occupancy": "A",
                "hotelCode": "A",
                "locationCode": "A"
            }

+ Response 200 (application/xml;charset=UTF-8)

    + Body

<!-- include markdown-pp (without spaces before) -->
<csw:GetRecordsResponse xmlns:csw="http://www.opengis.net/cat/csw" xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:dct="http://www.purl.org/dc/terms/" xsi:schemaLocation="http://www.opengis.net/cat/csw https://:8888/SpatialWS-SpatialWS-context-root/cswservlet?recordTypeId=1 " version="2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <csw:RequestId>4</csw:RequestId>
   <csw:SearchStatus status="complete"/>
   <csw:SearchResults recordSchema="http://www.opengis.net/cat/csw" numberOfRecordsMatched="1" numberOfRecordsReturned="1" nextRecord="0" expires="2007-02-09T16:32:35.29Z">
      <csw:Record xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:ows="http://www.opengis.net/ows" xmlns:dct="http://www.purl.org/dc/terms/">
         <dc:contributor xmlns:dc="http://www.purl.org/dc/elements/1.1/" scheme="http://www.example.com">Raja</dc:contributor>
         <dc:identifier xmlns:dc="http://www.purl.org/dc/elements/1.1/">REC-1</dc:identifier>
      </csw:Record>
   </csw:SearchResults>
</csw:GetRecordsResponse>

它将准备好加载到您的模拟服务器中。

生成 HTML 文档和加载到模拟服务器中的文件

./bin/split-blue c <path>

示例 1

./bin/split-blue c md

它将尝试搜索所有名为 index.apib 的文件以处理该文件的包含语句，并在 Build 文件夹中生成输出文件（out.apib 和 out.html），如果该文件夹不存在，则在其与 index.apib 文件相同的级别创建它

示例内容 index.apib

!INCLUDE "../cancel-api.apib"
!INCLUDE "../valuate-api.apib"

因此，此命令将生成以下文件

• md/example/MyAPI/V1/Compile/Build/out.apib
• md/example/MyAPI/V1/Compile/Build/out.html
• md/example/MyAPI/V2/Compile/Build/out.apib
• md/example/MyAPI/V2/Compile/Build/out.html

示例 2

./bin/split-blue c md/example/MyAPI/V2

• md/example/MyAPI/V2/Compile/Build/out.apib
• md/example/MyAPI/V2/Compile/Build/out.html

它将生成以下文件

测试

您可以使用以下命令执行集成测试

vendor/bin/phpunit

屏幕截图

./bin/split-blue c md/example/MyAPI/V2