Documentation/WADL 约定

OpenStack 文档

文档贡献者指南 — 新手指南 — 构建文档 — 专业团队 — 文档团队办公时间

文档规范

写作风格 - 标记约定 - WADL 约定 - 指南约定 - JSON 约定 - 文档结构

警告

此页面已弃用。此处保留供参考。

此页面提供 WADL 风格和标记约定，目前正在进行中。

什么是 WADL？

有关 WADL 语言的完整信息，请参阅 Web Application Description Language (http://www.w3.org/Submission/wadl/)。

写作风格

确保每个资源都有唯一的 ID。当你在 XML 文件中包含 WADL 资源时，你通过 ID 引用它。
将 JSON 请求放在 XML 请求之前，将 JSON 响应放在 XML 响应之前。为什么？JSON 比 XML 更常用。
对于方法标题使用句子风格的大小写。
将参数描述放在 <param> 标签内，而不是放在表格中。
务必描述所有参数 - 模板、标头、普通参数等。
务必描述所有响应字段和响应标头。
包括所有可能的成功和错误代码。
如果该方法同时具有请求体和响应体，请包含 JSON 和 XML 的代码示例。

最佳实践

拼写检查 WADL。
删除多余的空白。
保持描述简洁。
对代码示例使用此命名约定

JSON: resource_method_type.json。例如，对于“创建服务器请求”，servers_post_request.json。

XML: resource_method_type.xml。例如，对于“创建服务器请求”，servers_post_request.xml。

HTTP 标头：resource_method_lang_http_type.txt。例如，对于“创建服务器请求”的 HTTP 标头，servers_post_json_http_request.txt

验证代码示例。使用 oXygen 验证 XML 示例。使用 http://trentm.com/json/ 命令行工具来格式化和验证 JSON。

例如

json -o json-4 -f KeyCreateRequest.json

标记

参数

参数的正确位置是以下位置之一

作为资源的一个子元素

<resource id="tenant_id" path="{tenant_id}">
    <param name="tenant_id" style="template" type="xsd:string">
        <wadl:doc xmlns="http://docbook.org/ns/docbook"  xml:lang="EN" title="Tenant ID">
            <para>The ID for the tenant or account in a multi-tenancy cloud.</para>
        </wadl:doc>
    </param>
       . . .
</resource>

作为请求或响应表示的一个子元素，在结束 </representation> 标签之前。最好放在 XML 表示中

<request>
    <representation mediaType="application/json">
        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause server: JSON request">
            <xsdxt:code href="../api_samples/os-admin-actions/admin-actions-pause.json"/>
        </wadl:doc>
    </representation>
    <representation mediaType="application/xml">
        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause server: XML request">
            <xsdxt:code href="../api_samples/os-admin-actions/admin-actions-pause.xml"/>
        </wadl:doc>
        <param name="pause" style="plain" type="xsd:string" required="true">
            <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN" title="Pause action">
                <para>Specify the <code>pause</code> action in the request body.</para>
            </wadl:doc>
        </param>
    </representation>
</request>

标题

<method name="GET" id="getVolume">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
            title="Show volume details">

对于标题使用句子风格的大小写。遵循此约定进行标题文本

方式	示例标题
创建 (POST)	创建卷
列出 (GET)	列出卷
显示 (GET)	显示卷详细信息
更新 (PUT)	更新卷
删除 (DELETE)	删除卷

简短描述

<method name="GET" id="getVolume">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
            title="Show volume details">
            <para role="shortdesc">Shows volume details.</para>

使简短描述简短。将额外内容放在后续的 <para> 标签中。

遵循此约定进行简短描述文本

方式	示例简短描述	不要使用
创建 (POST)	创建卷。	创建卷。创建一个新的卷。
列出 (GET)	列出卷。	获取卷的列表。打印卷的列表。检索卷的列表。
显示 (GET)	显示卷详细信息。显示镜像详细信息。显示指定超visor的启动时间。	检索信息或获取信息。
更新 (PUT)	更新卷详细信息。
删除 (DELETE)	删除卷。	删除卷。永久销毁卷。

故障排除验证错误

如果引用 WADL 的书籍的构建因验证错误而中断，如下所示

2014-07-27 21:20:15.285 | @@@@@@@@@@@@@@@@@@@@@@
2014-07-27 21:20:15.285 | !!!VALIDATION ERRORS!!
2014-07-27 21:20:15.285 | !!!!!!!!!!!!!!!!!!!!!!
2014-07-27 21:20:15.285 | 
2014-07-27 21:20:15.285 | Note: Open the temporary file:
2014-07-27 21:20:15.285 | 
2014-07-27 21:20:15.285 | file:/home/jenkins/workspace/gate-identity-api-tox-doc-publish-checkbuild/v2.0/target//identity-dev-guide.xml-invalid-idrefs.xml

完成以下步骤以诊断问题

在 oXygen 中打开 *-invalid-idrefs.xml 文件。在本例中，将打开 identity-dev-guide.xml-invalid-idrefs.xml。
验证文件并转到错误的第一行。
以 Author 模式查看。
向上滚动以找到最接近的方法 - 这通常是出错的方法。
克隆并构建 api-site/api-ref pom.xml 文件。如果构建成功，则问题在于源 DocBook 文件而不是 WADL 文件。如果构建不成功，则问题在于 WADL 文件。

DOCBOOK 文件问题

在 api-site/api-ref 中找到与导致中断的文件匹配的章节文件。例如，如果 identity-api/v2.0/src/ch_identity-client-api.xml 是错误的来源，请找到平行的 api-site/api-ref/src/docbkx/ch_identity-v2.xml 文件。
在 oXygen 中打开 ch_identity-client-api.xml 和 ch_identity-v2.xml，并比较这些文件。更新 ch_identity-client-api.xml 中对 WADL 的引用，以匹配 ch_identity-v2.xml 中的引用。但是，请确保指向 WADL 的原始版本，如下所示：

<wadl:resource href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/wadl/identity-admin.wadl#admin-extensions">

WADL 问题

在 oXygen 中打开有错误的 WADL 文件。
导航到出错的方法。
查找缺少的 ID、重复的 ID 和不正确的标记。
如果找不到错误，请查看引用此 WADL 的 DocBook 文件。查找对同一方法的重复调用。查找不正确的方法调用 - 例如，方法名称已更改，但对该方法的引用是对旧方法名称的引用。