apidoc 源码分析 Functions

Question

Package apidoc RESTful API 文档生成工具

从代码文件的注释中提取特定格式的内容，生成 RESTful API 文档，支持大部分的主流的编程语言。

Constants

const (
	// LSPVersion 当前支持的 language server protocol 版本
	LSPVersion = lsp.Version

	// DocVersion 文档的版本
	DocVersion = ast.Version
)

Functions

func

func Buffer(h *core.MessageHandler, o *build.Output, i ...*build.Input) (*bytes.Buffer, error)

Buffer 生成文档内容并返回

如果是文档语法错误，则相关的错误信息会反馈给 h，由 h 处理错误信息； 如果是配置项（o 和 i）有问题，则以 *core.Error 类型返回错误信息。

NOTE: 如果需要从配置文件进行构建文档，可以采用 Config.Buffer

func

func Build(h *core.MessageHandler, o *build.Output, i ...*build.Input) error

Build 解析文档并输出文档内容

如果是文档语法错误，则相关的错误信息会反馈给 h，由 h 处理错误信息； 如果是配置项（o 和 i）有问题，则以 *core.Error 类型返回错误信息。

NOTE: 如果需要从配置文件进行构建文档，可以采用 Config.Build

func

func CheckSyntax(h *core.MessageHandler, i ...*build.Input)

CheckSyntax 测试文档语法

func

func Locale() language.Tag

Locale 获取当前设置的本地化 ID

func

func Locales() []language.Tag

Locales 返回当前所有支持的本地化信息

func

func Mock(h *core.MessageHandler, data []byte, o *MockOptions) (http.Handler, error)

Mock 根据文档数据生成 Mock 中间件

data 为文档内容； o 用于生成 Mock 数据的随机项，如果为 nil，则会采用默认配置项；

func

func MockFile(h *core.MessageHandler, path core.URI, o *MockOptions) (http.Handler, error)

MockFile 根据文档生成 Mock 中间件

path 为文档路径； o 用于生成 Mock 数据的随机项，如果为 nil，则会采用默认配置项；

func

func Pack(h *core.MessageHandler, opt *PackOptions, o *build.Output, i ...*build.Input) error

Pack 将文档内容打包成一个 Go 文件

opt 用于指定打包的设置项，如果为空，则会使用一个默认的设置项， 该默认设置项会在当前目录下创建一个包为 apidoc 的包，且公开文档数据为 APIDOC， 用户可以使用 Unpack 解包该常量的内容，即为一个合法的 apidoc 文档。

func

func ServeLSP(header bool, t, addr string, timeout time.Duration, infolog, errlog *log.Logger) error

ServeLSP 提供 language server protocol 服务

header 表示传递内容是否带报头； t 表示允许连接的类型，目前可以是 tcp、udp、stdio 和 unix； timeout 表示服务端每次读取客户端时的超时时间，如果为 0 表示不会超时。 超时并不会出错，而是重新开始读取数据，防止被读取一直阻塞，无法结束进程；

func

func SetLocale(tag language.Tag)

SetLocale 设置当前的本地化 ID

如果不调用此函数，则默认会采用 internal/locale.DefaultLocaleID 的值。 如果想采用当前系统的本地化信息，可以使用 github.com/issue9/localeutil.SystemLanguageTag 函数。

func

func Static(dir core.URI, stylesheet bool) http.Handler

Static 为 dir 指向的路径内容搭建一个静态文件服务

dir 为静态文件的根目录，一般指向 /docs 用于搭建一个本地版本的 https://apidoc.tools，默认页为 index.xml。 如果 dir 值为空，则会采用内置的文档内容作为静态文件服务的内容。

stylesheet 表示是否只展示 XSL 及相关的内容。

用户可以通过以下代码搭建一个简易的 https://apidoc.tools 网站：

http.Handle("/apidoc", apidoc.Static(...))

func

func Unpack(buffer string) (string, error)

Unpack 用于解压由 Pack 输出的内容

func

func Version(full bool) string

Version 当前程序的版本号

full 表示是否需要在版本号中包含编译日期和编译时的 Git 记录 ID。

func

func View(status int, url string, data []byte, contentType string, dir core.URI, stylesheet bool) http.Handler

View 返回查看文档的中间件

提供了与 Static 相同的功能，同时又可以额外添加一个文件。 与 Buffer 结合，可以提供一个完整的文档查看功能。

status 是新文档的返回的状态码； url 表示文档在路由中的地址； data 表示文档的实际内容，会添加 xml-stylesheet 指令，并指向当前的 apidoc.xsl； contentType 表示文档的 Content-Type 报头值； dir 和 stylesheet 则和 Static 相同。

func

func ViewFile(status int, url string, path core.URI, contentType string, dir core.URI, stylesheet bool) (http.Handler, error)

ViewFile 返回查看文件的中间件

功能等同于 View，但是将 data 参数换成了文件地址。 url 可以为空值，表示接受 path 的文件名部分作为其值。

path 可以是远程文件，也可以是本地文件。

func

func ViewPack(status int, url string, unpackData string, contentType string, dir core.URI, stylesheet bool) http.Handler

ViewPack 返回查看文档的中间件

功能基本与 View 相同，但是第三个参数 unpackData 为 Pack() 函数打包之内的内容， 不需要调用 Unpack() 解包，直接由 ViewPack 自行解包。

<h2ocumentation-typesHeader">Types

type

type Config = build.Config

Config 配置文件 apidoc.yaml 所表示的内容
<h3ocumentation-type">type

type MockOptions struct {
	Indent    string// 缩进字符串	Servers   map[string]string// 为文档中所有 server 以及对应的路由前缀。	SliceSize Range// 指定用于生成数组大小范围的数值
	NumberSize  Range// 指定用于生成数值数据的范围	EnableFloat bool// 是否允许生成浮点数
	StringSize  Range// 指定生成随机字符串的长度范围	StringAlpha []byte// 指定生成字符串可用的字符
	URLDomains        []string// 指定生成 url 类型数据时可用的域名，默认为 example.com	EmailDomains      []string// 指定生成 email 类型数据时可用的域名，默认为 example.com	EmailUsernameSize Range// 指定生成 email 类型数据的用户名长度范围，默认 [3,8]
	ImageBasePrefix string// 图片的基地址
	DateStart time.Time// 指定生成与时间相关的数值时的最小值	DateEnd   time.Time// 指定生成与时间相关的数值时的最大值	// contains filtered or unexported fields
}

MockOptions mock 的一些随机设置项

type

type PackOptions = build.PackOptions

PackOptions 指定了打包文档内容的参数

type

type Range struct {
	Min, Max int}

Range 表示数值的范围

命令行方法

大致的使用方法为：

apidoc cmd [args]

其中的 cmd 为子命令，args 代码传递给该子命令的参数。 可以使用 help 查看每个子命令的具体说明：

apidoc help [cmd]