apidoc 文档格式

Question

文档采用 XML 格式。存在两个顶级标签：apidoc 和 api，用于描述整体内容和具体接口信息。

文档被从注释中提取之后，最终会被合并成一个 XML 文件，在该文件中 api 作为 apidoc 的一个子元素存在，如果你的项目不想把文档写在注释中，也可以直接编写一个完整的 XML 文件，将 api 作为 apidoc 的一个子元素。

具体可参考 示例代码。

以下是对各个 XML 元素以及参数介绍，其中以 @ 开头的表示 XML 属性；. 表示为当前元素的内容；其它表示子元素。

apidoc

用于描述整个文档的相关内容，只能出现一次。

名称	类型	必填	描述
@apidoc	string		文档的版本要号
@lang	string		文档内容的本地化 ID，比如 zh-Hans、en-US 等。
@logo	string		文档的图标，仅可使用 SVG 格式图标。
@created	date		文档的创建时间
@version	version		文档的版本号
xml-namespace	xml-namespace[]		针对 application/xml 类型的内容的命名空间设置
title	string		文档的标题
description	richtext		文档的整体描述内容
contact	contact		文档作者的联系方式
license	link		文档的版权信息
tag	tag[]		文档中定义的所有标签
server	server[]		API 基地址列表，每个 API 最少应该有一个 server。
api	api[]		文档中的 API 文档
header	param[]		文档中所有 API 都包含的公共报头
response	request[]		文档中所有 API 文档都需要支持的返回内容
mimetype	string[]		文档所支持的 mimetype

xml-namespace

为 application/xml 定义命名空间的相关属性

名称	类型	必填	描述
@prefix	string		命名空间的前缀，如果为空，则表示作为默认命名空间，命局只能有一个默认命名空间。
@urn	string		命名空间的唯一标识，需要全局唯一，且区分大小写。

richtext

富文本内容

名称	类型	必填	描述
@type	string		指定富文本内容的格式，目前支持 html 和 markdown。
.	string		富文本的实际内容

contact

用于描述联系方式

名称	类型	必填	描述
@name	string		联系人的名称
url	string		联系人的 URL
email	string		联系人的电子邮件

link

用于描述链接信息，一般转换为 HTML 的 a 标签。

名称	类型	必填	描述
@text	string		链接的字面文字
@url	string		链接指向的文本

tag

用于对各个 API 进行分类

名称	类型	必填	描述
@name	string		标签的唯一 ID
@title	string		标签的字面名称
@deprecated	version		该标签在大于该版本时被弃用

server

用于指定各个 API 的服务器地址

名称	类型	必填	描述
@name	string		服务唯一 ID
@url	string		服务的基地址，与该服务关联的 API，访问地址都是相对于此地址的。
@deprecated	version		服务在大于该版本时被弃用
@summary	string		服务的摘要信息
description	richtext		服务的详细描述

api

用于定义单个 API 接口的具体内容

名称	类型	必填	描述
@version	version		表示此接口在该版本中添加
@method	string		当前接口所支持的请求方法
@id	string		接口的唯一 ID
@summary	string		简要介绍
@deprecated	version		在此版本之后将会被弃用
path	path		定义路径信息
description	richtext		该接口的详细介绍，为 HTML 内容。
request	request[]		定义可用的请求信息
response	request[]		定义可能的返回信息
callback	callback		定义回调接口内容
header	param[]		传递的报头内容，如果是某个 mimetype 专用的，可以放在 request 元素中。
tag	string[]		关联的标签
server	string[]		关联的服务

path

用于定义请求时与路径相关的内容

名称	类型	必填	描述
@path	string		接口地址
param	param[]		地址中的参数
query	param[]		地址中的查询参数

param

参数类型，基本上可以作为 request 的子集使用。

名称	类型	必填	描述
@xml-attr	bool		是否作为父元素的属性，仅作用于 XML 元素。是否作为父元素的属性，仅用于 XML 的请求。
@xml-extract	bool		将当前元素的内容作为父元素的内容，要求父元素必须为 object。
@xml-cdata	bool		当前内容为 CDATA，与 @xml-attr 互斥。
@xml-ns-prefix	string		XML 标签的命名空间名称前缀
@xml-wrapped	string		如果当前元素的 @array 为 true，则可以通过此值指定在 XML 格式中的名称。 可以有三种格式： name：表示为数组添加一个父元素名称为 name； name1>name2：表示数组项的名称改为 name2，且添加一个父元素名为 name1； >name：表示将当前数组元素的名称改为 name；
@name	string		值的名称
@type	type		值的类型
@deprecated	version		表示在大于等于该版本号时不再启作用
@default	string		默认值
@optional	bool		是否为可选的参数
@array	bool		是否为数组
@summary	string		简要介绍
@array-style	bool		以数组的方式展示数据
param	param[]		子类型，比如对象的子元素。
enum	enum[]		当前参数可用的枚举值
description	richtext		详细介绍，为 HTML 内容。

enum

定义枚举类型的数所的枚举值

名称	类型	必填	描述
@deprecated	version		该属性弃用的版本号
@value	string		枚举值
@summary	string		枚举值的说明
description	richtext		枚举值的详细说明

request

定义了请求和返回的相关内容

名称	类型	必填	描述
@xml-attr	bool		是否作为父元素的属性，仅作用于 XML 元素。是否作为父元素的属性，仅用于 XML 的请求。
@xml-extract	bool		将当前元素的内容作为父元素的内容，要求父元素必须为 object。
@xml-cdata	bool		当前内容为 CDATA，与 @xml-attr 互斥。
@xml-ns-prefix	string		XML 标签的命名空间名称前缀
@xml-wrapped	string		如果当前元素的 @array 为 true，则可以通过此值指定在 XML 格式中的名称。 可以有三种格式： name：表示为数组添加一个父元素名称为 name； name1>name2：表示数组项的名称改为 name2，且添加一个父元素名为 name1； >name：表示将当前数组元素的名称改为 name；
@name	string		当 mimetype 为 application/xml 时，此值表示 XML 的顶层元素名称，否则无用。
@type	type		值的类型
@deprecated	version		表示在大于等于该版本号时不再启作用
@array	bool		是否为数组
@summary	string		简要介绍
@status	number		状态码。在 request 中，该值不可用，否则为必填项。
@mimetype	string		媒体类型，比如 application/json 等。
enum	enum[]		当前参数可用的枚举值
param	param[]		子类型，比如对象的子元素。
example	example[]		示例代码
header	param[]		传递的报头内容
description	richtext		详细介绍，为 HTML 内容。

example

示例代码

名称	类型	必填	描述
@mimetype	string		特定于类型的示例代码
@summary	string		示例代码的概要信息
.	string		示例代码的内容，需要使用 CDATA 包含代码。

callback

定义接口的回调内容

名称	类型	必填	描述
@method	string		回调的请求方法
@summary	string		简要介绍
@deprecated	version		在此版本之后将会被弃用
path	path		回调的请求地址
description	richtext		对于回调的详细介绍
response	request[]		定义可能的返回信息
request	request[]		定义可用的请求信息
header	param[]		传递的报头内容

string

普通的字符串类型，特殊字符需要使用 XML 实体，比如 < 需要使用 < 代替。

date

采用 RFC3339 格式表示的时间，比如：2019-12-16T00:35:48+08:00。

version

版本号，格式遵守 semver 规则。比如：1.0.1、1.0.1+20200618。

bool

布尔值类型，取值为 true 或是 false。

type

用于表示数据的类型值，格式为 primitive[.subtype]，其中 primitive 为基本类型，而 subtype 为子类型，用于对 primitive 进行进一步的约束，当客户端无法处理整个类型时，可以按照 primitive 的类型处理。
目前支持以下几种类型：

• 空值；
• bool 布尔值；
• object 对象；
• number 数值类型；
• number.int 整数类型的数值；
• number.float 浮点类型的数值；
• string 字符串；
• string.url URL 类型的字符串；
• string.email email 类型的字符串；
• string.image 表示图片地址的 URL；
• string.date 表示 RFC3339 中的 full-date 日期格式，比如 2020-01-02；
• string.time 表示 RFC3339 中的 full-time 时间格式，比如 15:16:17Z、15:16:17+08:00；
• string.date-time 表示 RFC3339 中的 date-time 格式，比如 2020-01-02T15:16:17-08:00；

number

普通的数值类型，比如：1、-11.1 等。