apidoc

package module
v7.2.4 Latest Latest
Warning

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

 Go to latest Published: Jun 2, 2022 License: MIT Imports: 16 Imported by: 0

README

apidoc

Test Status Latest Release Go Report Card codecov Go version 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
}

使用

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

参与开发

请阅读 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) error

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 ServeLSP 

func ServeLSP(header bool, t, addr string, timeout time.Duration, info, erro *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, erro *log.Logger) http.Handler

Static 为 dir 指向的路径内容搭建一个静态文件服务

dir 为静态文件的根目录，一般指向 /docs 用于搭建一个本地版本的 https://apidoc.tools，默认页为 index.xml。 如果 dir 值为空，则会采用内置的文档内容作为静态文件服务的内容。

stylesheet 表示是否只展示 XSL 及相关的内容。

用户可以通过以下代码搭建一个简易的 https://apidoc.tools 网站： 

http.Handle("/apidoc", apidoc.Static(...))

func Version 

func Version(full bool) string

Version 当前程序的版本号

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

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 Range 

type Range struct {
	Min, Max int
}

Range 表示数值的范围

type Server added in v7.2.3 

type Server struct {
	Status      int         // 默认值为 200
	Path        string      // 文档在路由中的地址，默认值为 apidoc.xml
	ContentType string      // 文档的 ContentType，为空表示采用 application/xml
	Dir         core.URI    // 除文档不之外的附加项，比如 xsl，css 等内容的所在位置，如果为空表示采用内嵌的数据；
	Stylesheet  bool        // 是否只采用 Dir 中的 xsl 和 css 等样式数据，而忽略其它文件
	Erro        *log.Logger // 服务出错时的错误信息输出通道，默认采用 log.Default()
}

Server 用于生成查看文档中间件的配置项

func (*Server) Buffer added in v7.2.3 

func (srv *Server) Buffer(buf []byte) http.Handler

Buffer 将 buf 作为文档内容生成中间件

func (*Server) File added in v7.2.3 

func (srv *Server) File(path core.URI) (http.Handler, error)

File 将 path 指向的内容作为文档内容生成中间件

Source Files

View all Source files

Directories

Path Synopsis
Package build 提供构建文档的相关功能
 Package build 提供构建文档的相关功能
cmd
apidoc
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.