apidoc 文档格式 - 文章教程

apidoc 文档格式

发布于 2021-10-10 字数 19854 浏览 941 评论 0

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

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

具体可参考 示例代码

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

apidoc

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

名称 类型 必填 描述
@apidoc string 文档的版本要号
@lang string 文档内容的本地化 ID,比如 zh-Hansen-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 指定富文本内容的格式,目前支持 htmlmarkdown
. 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 如果当前元素的 @arraytrue,则可以通过此值指定在 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 如果当前元素的 @arraytrue,则可以通过此值指定在 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 实体,比如 < 需要使用 &lt; 代替。

date

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

version

版本号,格式遵守 semver 规则。比如:1.0.11.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:17Z15:16:17+08:00
  • string.date-time 表示 RFC3339 中的 date-time 格式,比如 2020-01-02T15:16:17-08:00

number

普通的数值类型,比如:1-11.1 等。

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2512 文章
30 评论
83580 人气
更多

推荐作者

魏剑帆

文章 0 评论 0

yanggwq

文章 0 评论 0

qq_c2gI5

文章 0 评论 0

qq_iQVWB

文章 0 评论 0