apidoc

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
}

安装

go get github.com/caixw/apidoc

支持多种本地化语言，默认情况下会根据当前系统所使用的语言进行调整。 也可以通过设置环境变更 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.Buffer(h, output, inputs...)

参与开发

请阅读 CONTRIBUTING.md 文件的相关内容。

版权

本项目源码采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

文档内容的版权由各个文档各自表述。

Documentation

Overview

Package apidoc RESTful API 文档生成工具

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

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)
• func MakeBuffer(h *message.Handler, wd string) (*bytes.Buffer, time.Duration)
• func Site(dir string) http.Handler
• func Version() string

Functions

func Buffer

func Buffer(h *message.Handler, o *output.Options, i ...*input.Options) (*bytes.Buffer, error)

Buffer 生成文档内容，并保存在内存。

func Detect

func Detect(wd string, recursive bool) error

Detect 检测 wd 目录，并根据目录情况写入配置文件到该目录。

func Do

func Do(h *message.Handler, o *output.Options, i ...*input.Options) error

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

如果需要控制详细的操作步骤，可以自行调用 input 和 output 的相关函数实现。

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

NOTE: 需要先调用 Init() 初始化本地化信息。

func Init

func Init(tag language.Tag) error

Init 初始化包

如果传递了 language.Und，则采用系统当前的本地化信息。 如果获取系统的本地化信息依然失败，则会失放 zh-Hans 作为默认值。

func Make

func Make(h *message.Handler, wd string, test bool)

Make 根据 wd 目录下的配置文件生成文档

test 表示是否仅测试该配置文件和文档的正确性。

NOTE: 需要先调用 Init() 初始化本地化信息。

func MakeBuffer

func MakeBuffer(h *message.Handler, wd string) (*bytes.Buffer, time.Duration)

MakeBuffer 根据 wd 目录下的配置文件生成文档内容并保存至内存

NOTE: 需要先调用 Init() 初始化本地化信息。

func Site

func Site(dir string) http.Handler

Site 将 dir 作为静态文件服务内容

默认页为 index.xml，同时会过滤 CNAME， 如果将 dir 指同 docs 目录，相当于本地版本的 https://apidoc.tools

用户可以通过诸如：

http.Handle("/apidoc", apidoc.Site("./docs"))

的代码搭建一个简易的 https://apidoc.tools 网站。

func Version

func Version() string

Version 当前程序的版本号

为一个正常的 semver(https://semver.org/lang/zh-CN/) 格式字符串。