apidoc 简单的 RESTful API 文档生成工具 - 文章教程

apidoc 简单的 RESTful API 文档生成工具

发布于 2021-09-30 字数 3435 浏览 808 评论 0

apidoc 是一个简单的 RESTful API 文档生成工具,它从代码注释中提取特定格式的内容,生成文档。

目前支持以下语言:C#、C/C++、D、Dart、Erlang、Go、Groovy、Java、JavaScript、Julia、Kotlin、Lisp/Clojure、Lua、Nim、Pascal/Delphi、Perl、PHP、Python、Ruby、Rust、Scala、Swift、Typescript 和 Zig。

具体文档可参考: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
}

使用

macOS 和 linux 可以使用 homebrew 安装:

brew tap caixw/brew
brew install caixw/brew/apidoc

同时在 https://github.com/caixw/apidoc/releases 提供了部分主流系统下的可用二进制。

如果你使用的系统不在此列,则需要手动下载编译:

git clone https://github.com/caixw/apidoc.git
cd apidoc
./scripts/build.sh

支持多种本地化语言,默认情况下会根据当前系统所使用的语言进行调整。也可以通过设置环境变更 LANG 指定一个本地化信息。*nix 系统也可以使用以下命令:

LANG=lang apidoc # lang 设置为你需要的语言 ID,比如 zh-hans 等。

具体的安装和使用细节可参考 https://apidoc.tools/#usage

集成

若需要将 apidoc 当作包集成到其它 Go 程序中,可参考以下代码:

import (
    "golang.org/x/text/language"

    "github.com/caixw/apidoc/v7"
    "github.com/caixw/apidoc/v7/core"
    "github.com/caixw/apidoc/v7/build"
)

// 初始本地化内容
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

项目地址:https://github.com/caixw/apidoc/

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

扫码加入群聊

发布评论

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

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

关于作者

JSmiles

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

2512 文章
30 评论
81914 人气
更多

推荐作者

qq_iQVWB

文章 0 评论 0

gyhjy

文章 0 评论 0

dianjvnan

文章 0 评论 0