WebYaST

主页 - 安装 - 文档 - 架构 - 开发

文档化 YaST REST 服务 API

本文档描述了如何编写 YaST REST 服务的文档。

概述

WebYaST 使用 restility 工具生成文档。它包含在 rubygem-restility 包中。

文档是用单独的纯文本文件编写的，restility 会将其转换为 HTML 文档。生成的文档存储在 public/ 子目录中。这意味着文档可以直接在 REST 服务中访问。

插件中的目录结构

文档源是从插件目录中位于 restdoc/api.txt 文件中读取的。

问题是如何定义生成文档的目标路径。它必须对每个插件都是唯一的，以避免文件冲突，并且必须在插件本身中设置。

因此，输出生成到 public/*/restdoc/ 子目录中 - rake 任务会在 public/ 子树中的某个位置搜索 restdoc 目录。应该只有一个 restdoc 目录（找到的第一个目录将被使用）。

示例：系统插件的文档在 https://:8080/system/restdoc/index.html 处可用

生成文档

定义了一个使用 restility 生成文档的 rake 任务。

手动生成

调用 rake restdoc 以手动生成文档。文档将生成到 restdoc 目录中。

在编写文档时使用此调用，以便立即检查生成的结果。

自动生成

文档应该在软件包构建期间自动生成。要启用自动生成，请将这些部分添加到 .spec 文件中

 BuildRequires:  rubygem-yast2-webservice-tasks rubygem-restility

 %build
 # create the output directory for the generated documentation
 mkdir -p public/controller_name/restdoc
 # build restdoc documentation
 export RAILS_PARENT=/srv/www/yastws
 env LANG=en rake restdoc

 # do not package restdoc sources
 rm -rf restdoc

这些行确保 RPM 包包含最新的生成文档，并且文档源不会包含在包中。当 restility 包更新时，文档也会被重新生成。

应该文档化的内容

REST API 文档的一个很好的示例是 Twitter 文档。

需要文档化的最重要的内容是

模块的目的，它可以做什么 - 基本概述
是否需要登录？（通常是）
输入/输出格式（通常是 XML 和 JSON）
PolicyKit 访问权限列表，需要哪些权限才能读取，哪些权限才能写入...

然后，当然，应该描述 API 本身。每个函数都应该具有以下属性

请求类型（GET、POST、PUT 或 DELETE）
资源的 URL 路径（例如 /services/index.xml）。
约束 - 哪些值有效，哪些选项是必需的或可选的
特殊值 - 描述特殊值（如果适用）
返回值
如何报告错误或异常

文档的格式

输入格式

普通文本

文档文本行以至少一个空格字符（空格或制表符）开头。文本不会更改，可以直接使用 HTML 标记。

支持的关键字

以下是受支持的关键字列表，关键字必须位于行首（不允许空格）。

GET, PUT, POST, DELETE file_path - 开始一个新部分（函数），file_path 是 URL 中的路径
URL 中的参数应以这种方式记录

GET /path?param=<id>
   <b>id</b>: ID for ...

Contents - 此标签将被内容部分替换
Host: host_name - 指定服务的宿主名（对 WebYaST 没用，没有单个服务 URL）
<parameter_name> : description - 参数描述
XmlResult: xml_file - 请求的 XML 结果，这将生成指向 XML 文件的链接，xml_file 是不带 .xml 后缀的 XML 文件名
XmlBody: xml_file - XML 格式的输入，xml_file 是不带 .xml 后缀的 XML 文件名
Version: version - API 的版本

包含 XML 示例

XML 输出和输入示例放在单独的文件中。优点是可以轻松地使用 curl 创建它们，甚至可以将它们直接发送到 REST 服务器进行测试和验证它们是否正确且按预期工作。

使用 XmlBody 和 XmlRequest 关键字（参见上一段）。

请参阅 YaST 开发技巧，了解如何使用 curl 读取和发送 XML 文件。

api.txt 文件示例

= YaST REST Service Documentation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled "GNU Free Documentation License".

== System Service

Only authenticated users are allowed to access the API. Authentication is done
by sending a Basic HTTP Authorisation header.

All names aren't allowed to contain spaces, slashes or colons.

== Table of Contents

Contents:

== Formats

The system REST service supports only XML and JSON input/output formats.

== Overview

This module provides access to the basic system component. Curretly it provides only reboot and shutdown actions.

The module uses HAL as the backend, HAL daemon must be running to perform reboot/shutdown actions.

== PolicyKit Access Rights

The following PolicyKit permissions are needed to execute reboot and shutdown:

Reboot: org.freedesktop.hal.power-management.reboot

Shutdown: org.freedesktop.hal.power-management.shutdown

== System Actions

GET /system

Get the list of supported system actions. The list contains actions like <i>reboot</i> or <i>shutdown</i>.

CURL Example: curl -u user https://:4984/system.xml

XmlResult: system

PUT /system

Trigger a system action. Set active flag to true for the action which should be started - see the XML example file.

CURL example: curl -u user -X PUT -H 'Content-type: text/xml' -d @reboot_request.xml https://:4984/system.xml

XmlBody: reboot_request

XmlResult: reboot_response

openSUSE:WebYaST REST 服务文档