README
¶
apidoc
apidoc 是一个简单的 RESTful API 文档生成工具，它从代码注释中提取特定格式的内容，生成文档。 目前支持支持以下语言：C#、C/C++、D、Erlang、Go、Groovy、Java、JavaScript、Pascal/Delphi、 Perl、PHP、Python、Ruby、Rust、Scala 和 Swift。
具体文档可参考：https://apidoc.tools
/**
* <api method="GET" summary="获取所有的用户信息">
* <path path="/users">
* <query name="page" type="number" default="0" summary="显示第几页的内容" />
* <query name="size" type="number" default="20" summary="每页显示的数量" />
* </path>
* <tag>user</tag>
* <server>users</server>
* <response status="200" type="object" mimetype="application/json">
* <param name="count" type="int" optional="false" summary="符合条件的所有用户数量" />
* <param name="users" type="object" array="true" summary="用户列表">
* <param name="id" type="int" summary="唯一 ID" />
* <param name="name" type="string" summary="姓名" />
* </param>
* <example mimetype="application/json">
* <![CDATA[
* {
* "count": 500,
* "users": [
* {"id":1, "name": "管理员2"},
* {"id":2, "name": "管理员2"}
* ],
* }
* ]]>
* </example>
* </response>
* <response status="500" mimetype="application/json" type="object">
* <param name="code" type="int" summary="错误代码" />
* <param name="msg" type="string" summary="错误内容" />
* </response>
* </api>
*/
func login(w http.ResponseWriter, r *http.Request) {
// TODO
}
使用
在 https://github.com/caixw/apidoc/releases 提供了部分主流系统下的可用二进制。 如果你使用的系统不在此列，则需要手动下载编译。
支持多种本地化语言，默认情况下会根据当前系统所使用的语言进行调整。
也可以通过设置环境变更 LANG 指定一个本地化信息。*nix 系统也可以使用以下命令：
LANG=lang apidoc
将其中的 lang 设置为你需要的语言。
集成
若需要将 apidoc 当作包集成到其它 Go 程序中，可参考以下代码：
// 初始本地化内容
apidoc.SetLocale(language.MustParse("zh-Hans"))
// 可以自定义实现具体的错误处理方式
h := core.NewHandler(...)
output := &build.Output{...}
inputs := []*build.Input{...}
apidoc.Build(h, output, inputs...)
具体可查看文档：https://pkg.go.dev/github.com/caixw/apidoc/v7
参与开发
请阅读 CONTRIBUTING.md 文件的相关内容。
版权
本项目源码采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。
文档内容的版权由各个文档各自表述。
Documentation
¶
Overview ¶
Package apidoc RESTful API 文档生成工具
从代码文件的注释中提取特定格式的内容，生成 API 文档， 支持大部分的主流的编程语言。
Index ¶
- Constants
- func Buffer(h *core.MessageHandler, o *build.Output, i ...*build.Input) (*bytes.Buffer, error)
- func Build(h *core.MessageHandler, o *build.Output, i ...*build.Input) error
- func CheckSyntax(h *core.MessageHandler, i ...*build.Input)
- func Locale() language.Tag
- func Locales() []language.Tag
- func Mock(h *core.MessageHandler, data []byte, o *MockOptions) (http.Handler, error)
- func MockFile(h *core.MessageHandler, path core.URI, o *MockOptions) (http.Handler, error)
- func Pack(h *core.MessageHandler, opt *PackOptions, o *build.Output, i ...*build.Input) error
- func ServeLSP(header bool, t, addr string, infolog, errlog *log.Logger) error
- func SetLocale(tag language.Tag)
- func Static(dir core.URI, stylesheet bool) http.Handler
- func Unpack(buffer string) (string, error)
- func Version(full bool) string
- func View(status int, url string, data []byte, contentType string, dir core.URI, ...) http.Handler
- func ViewFile(status int, url string, path core.URI, contentType string, dir core.URI, ...) (http.Handler, error)
- func ViewPack(status int, url string, unpackData string, contentType string, dir core.URI, ...) http.Handler
- type Config
- type MockOptions
- type PackOptions
- type Range
Constants ¶
const ( // LSPVersion 获取当前支持的 LSP 版本 LSPVersion = lsp.Version // DocVersion 获取文档的版本信息 DocVersion = ast.Version )
Variables ¶
This section is empty.
Functions ¶
func Buffer ¶
Buffer 生成文档内容并返回
如果是文档语法错误，则相关的错误信息会反馈给 h，由 h 处理错误信息； 如果是配置项（o 和 i）有问题，则以 *message.SyntaxError 类型返回错误信息。
NOTE: 如果需要从配置文件进行构建文档，可以采用 Config.Buffer
func Build ¶
Build 解析文档并输出文档内容
如果是文档语法错误，则相关的错误信息会反馈给 h，由 h 处理错误信息； 如果是配置项（o 和 i）有问题，则以 *message.SyntaxError 类型返回错误信息。
NOTE: 如果需要从配置文件进行构建文档，可以采用 Config.Build
func Mock ¶
func Mock(h *core.MessageHandler, data []byte, o *MockOptions) (http.Handler, error)
Mock 生成 Mock 中间件
data 为文档内容； o 用于生成 Mock 数据的随机项，如果为 nil，则会采用默认配置项；
func MockFile ¶
func MockFile(h *core.MessageHandler, path core.URI, o *MockOptions) (http.Handler, error)
MockFile 生成 Mock 中间件
path 为文档路径； o 用于生成 Mock 数据的随机项，如果为 nil，则会采用默认配置项；
func Pack ¶
func Pack(h *core.MessageHandler, opt *PackOptions, o *build.Output, i ...*build.Input) error
Pack 将文档内容打包成一个 Go 文件
opt 用于指定打包的设置项，如果为空，则会使用一个默认的设置项， 该默认设置项会在当前目录下创建一个包为 apidoc 的包，且公开文档数据为 APIDOC， 用户可以使用 Unpack 解包该常量的内容，即为一个合法的 apidoc 文档。
func ServeLSP ¶
ServeLSP 提供 language server protocol 服务
header 表示传递内容是否带报头； t 表示允许连接的类型，目前可以是 tcp、udp、stdio 和 ipc
func Static ¶
Static 为 /docs 搭建一个静态文件服务
相当于本地版本的 https://apidoc.tools，默认页为 index.xml。
用户可以通过诸如：
http.Handle("/apidoc", apidoc.Static(...))
的代码搭建一个简易的 https://apidoc.tools 网站。
/docs 存放了整个项目的文档内容。其中根目录中包含网站的相关内容， 而 /v7 这些以版本号开头的则是查看 xml 文档的工具代码。 同时这一份代码也被编译在代码中。如果你不需要修改文档内容， 则可以直接传递空的 dir，表示采用内置的文档，否则指向指定的目录， 如果指向了自定义的目录，需要保证目录结构和文件名与 /docs 相同。 stylesheet 则指定了是否需要根目录的内容，如果为 true，只会提供转换工具的代码。
func Version ¶
Version 当前程序的版本号
包含了版本号，编译日期以及编译是的 Git 记录 ID。
为一个正常的 semver(https://semver.org/lang/zh-CN/) 格式字符串。
func View ¶
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 相同。
Types ¶
type MockOptions ¶
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 的一些随机设置项
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package build 提供构建文档的相关功能
|
Package build 提供构建文档的相关功能 |
|
cmd
|
|
|
apidoc
command
apidoc 是一个 RESTful API 文档生成工具 大致的使用方法为： apidoc cmd [args] 其中的 cmd 为子命令，args 代码传递给该子命令的参数。
|
apidoc 是一个 RESTful API 文档生成工具 大致的使用方法为： apidoc cmd [args] 其中的 cmd 为子命令，args 代码传递给该子命令的参数。 |
|
Package core 提供基础的核心功能
|
Package core 提供基础的核心功能 |
|
messagetest
Package messagetest 提供测试生成 message 相关的测试工具
|
Package messagetest 提供测试生成 message 相关的测试工具 |
|
internal
|
|
|
ast
Package ast 为 xml 服务的抽象语法树
|
Package ast 为 xml 服务的抽象语法树 |
|
ast/asttest
Package asttest 提供了一个合法的 ast.APIDoc 对象
|
Package asttest 提供了一个合法的 ast.APIDoc 对象 |
|
cmd
Package cmd 提供子命令的相关功能
|
Package cmd 提供子命令的相关功能 |
|
docs
Package docs 打包文档内容
|
Package docs 打包文档内容 |
|
docs/site
Package site 用于生成网站内容 包括网站的基本信息，以及文档的翻译内容等。
|
Package site 用于生成网站内容 包括网站的基本信息，以及文档的翻译内容等。 |
|
lang
Package lang 管理各类语言提取注释代码块规则的定义
|
Package lang 管理各类语言提取注释代码块规则的定义 |
|
lexer
Package lexer 提供基本的分词功能
|
Package lexer 提供基本的分词功能 |
|
locale
Package locale 提供了一个本地化翻译服务。
|
Package locale 提供了一个本地化翻译服务。 |
|
lsp
Package lsp 提供 language server protocol 服务
|
Package lsp 提供 language server protocol 服务 |
|
lsp/protocol
Package protocol 协议内容的定义
|
Package protocol 协议内容的定义 |
|
mock
Package mock 根据 doc 生成 mock 数据
|
Package mock 根据 doc 生成 mock 数据 |
|
node
Package node 处理 ast 中各个节点的结构信息 struct tag 标签属性分为 4 个字段，其中前三个是必填的： apidoc:"name,node-type,usage-key,omitempty" name 表示当前标签的名称，或是节点表示的类型； node-type 表示当前节点的类型，可以是以下值： - elem 表示这是一个子元素； - attr 表示为一个 XML 属性； - cdata 表示为 CDATA 数据； - content 表示为普通的字符串值； - meta 表示这个字段仅用于描述当前元素的元数据，比如元素的名称等； usage-key 指定了当前元素的翻译项； omitempty 表示当前值为空时，是否可以忽略。
|
Package node 处理 ast 中各个节点的结构信息 struct tag 标签属性分为 4 个字段，其中前三个是必填的： apidoc:"name,node-type,usage-key,omitempty" name 表示当前标签的名称，或是节点表示的类型； node-type 表示当前节点的类型，可以是以下值： - elem 表示这是一个子元素； - attr 表示为一个 XML 属性； - cdata 表示为 CDATA 数据； - content 表示为普通的字符串值； - meta 表示这个字段仅用于描述当前元素的元数据，比如元素的名称等； usage-key 指定了当前元素的翻译项； omitempty 表示当前值为空时，是否可以忽略。 |
|
openapi
Package openapi 实现 openapi 的相关数据类型 https://github.com/OAI/OpenAPI-Specification
|
Package openapi 实现 openapi 的相关数据类型 https://github.com/OAI/OpenAPI-Specification |
|
token
Package token 解析 xml 内容
|
Package token 解析 xml 内容 |