vmware/platypus

Platypus 镜像文档

镜像概述和主要用途

Platypus 是一项旨在改进多个 VMware 产品文档的计划，通过 Open API 进行描述，并使用 http://github.com/vmware/api-explorer/ 展示这些本地 API。默认配置下，Platypus 通过 VMware API 网络服务读取 https://code.vmware.com/apis 上的所有 API 定义，同时也会添加位于 platypus-api-additions 目录中的本地定义（添加方法见下文）。

核心功能和特性

• 多 API 同时提供：新版本无需更改容器即可同时提供所有 API，取代了之前一次只能使用一个 API 的限制
• 本地/远程 API 切换：通过页面左下角的"local"复选框可仅查看容器提供的 API，勾选"remote"可同时查看 VMware 官方 BETA 站点（https://code.vmware.com/apis%EF%BC%89%E4%B8%8A%E7%9A%84%E6%89%80%E6%9C%89 API 文档
• 支持添加自定义 API：可添加 Swagger JSON 文件作为本地 API 定义（目前仅支持 JSON 格式）

使用场景和适用范围

适用于需要查看、管理和扩展 VMware 产品 API 文档的开发人员、技术文档编写者及系统管理员，支持本地部署和自定义 API 文档集成。

使用方法和配置说明

直接运行容器

nightly 构建会发布到 Dockerhub，可直接使用以下命令在主机的 8080 端口运行容器（可将端口更改为其他可用端口，如 80）：

shell
docker run --rm --name platypus -p 8080:80 docker.xuanyuan.run/vmware/platypus

从旧版本迁移

之前的 Platypus 版本需要在 Swagger UI 中指定要访问的 API，且一次只能使用一个 API。新版本无需更改容器即可同时提供所有 API。若仅需查看容器内提供的 API，点击页面左下角的"local"复选框；若同时需要查看 VMware 官方 BETA 站点上的所有 API 文档，可同时点击"remote"。

构建和运行

1. 构建镜像：

shell
docker build -t platypus .

2. 运行容器（本地端口 8080）：

shell
docker run -p 8080:80 docker.xuanyuan.run/platypus

添加其他 API

若有 Swagger 文件，可将其添加为本地 API 定义，步骤如下：

1. 复制 Swagger JSON 文件（目前仅支持 JSON 格式，不支持 YAML），文件名需以"api-"开头并以".json"结尾
2. 编辑 local-apis.json 文件，添加新条目标识该文件，格式如下
3. 按上述步骤构建容器

local-apis.json schema 说明

json
{
    "api_uid": "api_photon_controller", 
    "name": "Photon Controller API", 
    "description": "Type some description for the API here.",
    "products": [
        "Photon Controller;1.1.1"
    ], 
    "resources": {
        "docs": []
    }, 
    "url": "local/swagger/api-photon.json", 
    "version": "1.1.1"
}

参数说明：

• api_uid：VMware 特定的 API 字符串 ID，可自定义或从 https://apigw.vmware.com/v1/m4/api/dcr/rest/apix/apis/uids 获取已知支持的 ID，用于关联 code.vmware.com 上的其他文档和示例代码
• name：API 的人类可读名称
• description：API 的描述信息
• products：提供该 API 的 VMware 产品列表，格式为"产品名称;版本号"（版本号可选），产品列表可从 https://apigw.vmware.com/v1/m4/api/dcr/rest/apix/products 获取
• resources：可选，可提供编程指南和其他文档的链接（格式较复杂，更多文档即将推出）
• url：容器内 HTTP 根目录到 Swagger 参考文档的相对 URL，Platypus 在容器中将所有 API 引用存放在"local/swagger"，因此需在此处前置 platypus-api-additions 文件夹中规范文件的文件名
• version：API 自身的版本号字符串（如有）

贡献

有改进 Platypus 的想法？

1. Fork Platypus 项目
2. 进行修改
3. 提交 PR