The highest tagged major version is
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">显示第几页的内容</query>
* <query name="size" type="number" default="20">每页显示的数量</query>
* </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="obj">
* <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.Init(language.MustParse("zh-Hans"))
// 可以自定义实现具体的错误处理方式
h := message.NewHandler(...)
output := &output.Options{...}
inputs := []*input.Options{
&input.Options{},
}
apidoc.Do(h, output, inputs...)
参与开发
请阅读 CONTRIBUTING.md 文件的相关内容。
版权
本项目源码采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。
文档内容的版权由各个文档各自表述。
Documentation
¶
Overview ¶
Package apidoc RESTful API 文档生成工具
可以从代码文件的注释中提取文档内容，生成 API 文档， 支持大部分的主流的编程语言。
在生成文档之前，请确保已经调用 Init() 用于初始化环境， Init() 可以确保能以你指定的本地化信息显示提示信息。
生成的文档，可以调用 Do() 输出为文件；也可以通过 Buffer() 返回 bytes.Buffer 实例；或者通过 Pack() 直接将文档与其依赖的 XSL 打包成一个 Go 源码文件，这样可以直接编译在二进制文件中。
Index ¶
- func Buffer(h *message.Handler, o *output.Options, i ...*input.Options) (*bytes.Buffer, error)
- func Detect(wd string, recursive bool) error
- func Do(h *message.Handler, o *output.Options, i ...*input.Options) error
- func Init(tag language.Tag) error
- func Make(h *message.Handler, wd string, test bool)deprecated
- func MakeBuffer(h *message.Handler, wd string) *bytes.Bufferdeprecated
- func Pack(h *message.Handler, url string, contentType, pkgName, varName, path string, ...) error
- func Site(dir string) http.Handlerdeprecated
- func Static(embedded []*static.FileInfo, dir string, t static.Type) http.Handler
- func Test(h *message.Handler, i ...*input.Options)
- func Version() string
- type Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Buffer ¶ added in v5.1.0
Buffer 生成文档内容并返回
如果是文档语法错误，则相关的错误信息会反馈给 h，由 h 处理错误信息； 如果是配置项（o 和 i）有问题，则以 *message.SyntaxError 类型返回错误信息。
NOTE: 需要先调用 Init() 初始化本地化信息
func Do ¶
Do 解析文档并输出文档内容
如果是文档语法错误，则相关的错误信息会反馈给 h，由 h 处理错误信息； 如果是配置项（o 和 i）有问题，则以 *message.SyntaxError 类型返回错误信息。
NOTE: 需要先调用 Init() 初始化本地化信息
func Pack ¶ added in v5.2.0
func Pack(h *message.Handler, url string, contentType, pkgName, varName, path string, t static.Type, o *output.Options, i ...*input.Options) error
Pack 同时将生成的文档内容与 docs 之下的内容打包
url 为文档的地址； contentType 为文档的类型，如果不指定，由 http.DetectContentType 获取； pkgName 打包的内容输出到 Go 文件时，该文件的包名； varName 内容保存的变量名； path 输出的 Go 文件地址； t 表示需要打包的文件类型；
chrome 浏览器限制了 XLS 与 XML 必须要遵守同源策略的限制， 这就限制了文档直接引用 https://apidoc.tools/v5/apidoc.xsl 文件的使用。
Pack() 可以将 XML 文档与 XSL 等内容打包为一个 Go 源码文件， 之后通过 Site() 建立文件服务，方便用户在二进制文件中直接建议文档服务。
func Static ¶ added in v5.2.0
Static 返回文件服务中间件
相当于本地版本的 https://apidoc.tools，默认页为 index.xml。
用户可以通过诸如：
http.Handle("/apidoc", apidoc.Static(...))
的代码搭建一个简易的 https://apidoc.tools 网站。
embedded 表示通过 Pack 打包之后的内容，如果该值不为空， 则在 embedded 中查找用户请求的内容； dir 表示文档的根目录，会在该目录下查找用户请求的文档内容。 当 embedded 为空时，dir 才启作用，dir 应该始终指向 /docs 目录， 如果是普通的文件静态服务，可以直接采用 http.FileServer 会更通用； t 表示可以访问的文件类型，仅对 dir 参数启作用。
NOTE: 只要 embedded 不为空，则只会采用 embedded 作为文件服务的主体内容。 dir 与 embedded 的区别在于：dir 指同一个本地目录，方便在运行时进行修改； 而 embedded 则直接将 /docs 内容内嵌到代码中，如果需要修改，则要重新编译代码才有效果。
func Version ¶
func Version() string
Version 当前程序的版本号
为一个正常的 semver(https://semver.org/lang/zh-CN/) 格式字符串。
Types ¶
type Config ¶ added in v5.2.0
type Config struct {
// 产生此配置文件的程序版本号
//
// 程序会用此来判断程序的兼容性。
Version string `yaml:"version"`
// 输入的配置项，可以指定多个项目
//
// 多语言项目，可能需要用到多个输入面。
Inputs []*input.Options `yaml:"inputs"`
// 输出配置项
Output *output.Options `yaml:"output"`
// contains filtered or unexported fields
}
Config 配置文件映身的结构
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
apidoc
apidoc 是一个 RESTful API 文档生成工具 大致的使用方法为： apidoc [options] [path] 具体的参数说明，可以使用 h 参数查看： apidoc -h path 表示目录列表，多个目录使用空格分隔。
|
apidoc 是一个 RESTful API 文档生成工具 大致的使用方法为： apidoc [options] [path] 具体的参数说明，可以使用 h 参数查看： apidoc -h path 表示目录列表，多个目录使用空格分隔。 |
|
site
简单地将 docs 作为一个 web 服务运行 可作为测试 xsl 使用，访问 localhost:8080/example 测试页面
|
简单地将 docs 作为一个 web 服务运行 可作为测试 xsl 使用，访问 localhost:8080/example 测试页面 |
|
Package doc 文档格式
|
Package doc 文档格式 |
|
Package input 用于处理输入的文件，从代码中提取基本的注释内容。
|
Package input 用于处理输入的文件，从代码中提取基本的注释内容。 |
|
internal
|
|
|
lang
Package lang 各类语言解析和管理。
|
Package lang 各类语言解析和管理。 |
|
locale
Package locale 提供了一个本地化翻译服务。
|
Package locale 提供了一个本地化翻译服务。 |
|
locale/syslocale
Package syslocale 获取所在系统的本地化语言信息。
|
Package syslocale 获取所在系统的本地化语言信息。 |
|
vars
Package vars 提供了一些公共的函数、结构体及代码级别的设置项。
|
Package vars 提供了一些公共的函数、结构体及代码级别的设置项。 |
|
Package message 各类输出消息的处理
|
Package message 各类输出消息的处理 |
|
Package output 对解析后的数据进行渲染输出。
|
Package output 对解析后的数据进行渲染输出。 |
|
Package static 提供了对 docs 中内容的处理方式
|
Package static 提供了对 docs 中内容的处理方式 |