apidoc

package module
v7.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 7, 2021 License: MIT Imports: 17 Imported by: 0

README

apidoc

Test Status Latest Release Go Report Card codecov PkgGoDev license

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
}

使用

在 https://github.com/caixw/apidoc/releases 提供了部分主流系统下的可用二进制。如果你使用的系统不在此列，则需要手动下载编译。

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

参与开发

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

版权

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

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

Documentation

Overview

Package apidoc RESTful API 文档生成工具

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

Index

Constants

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

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

Variables

This section is empty.

Functions

func Buffer 

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 Build 

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

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

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

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

func CheckSyntax 

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

CheckSyntax 测试文档语法

func Locale 

func Locale() language.Tag

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

func Locales 

func Locales() []language.Tag

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

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 

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 SetLocale 

func SetLocale(tag language.Tag)

SetLocale 设置当前的本地化 ID

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

func Static 

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 Unpack 

func Unpack(buffer string) (string, error)

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

func Version 

func Version(full bool) string

Version 当前程序的版本号

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

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 相同。

func ViewFile 

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 ViewPack 

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

ViewPack 返回查看文档的中间件

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

Types

type Config 

type Config = build.Config

Config 配置文件 apidoc.yaml 所表示的内容

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 的一些随机设置项

type PackOptions 

type PackOptions = build.PackOptions

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

type Range 

type Range struct {
	Min, Max int
}

Range 表示数值的范围

Source Files

View all 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 定义文档的抽象语法树
 Package ast 定义文档的抽象语法树
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
xmlenc
Package xmlenc 有关文档格式编解码处理
 Package xmlenc 有关文档格式编解码处理

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.