Documentation ¶
Overview ¶
Package ast 定义文档的抽象语法树
Index ¶
- Constants
- func ParseType(t string) (primitive, sub string)
- type API
- type APIDoc
- func (doc *APIDoc) Parse(h *core.MessageHandler, b core.Block)
- func (doc *APIDoc) ParseBlocks(h *core.MessageHandler, g func(chan core.Block))
- func (doc *APIDoc) Sanitize(p *xmlenc.Parser)
- func (doc *APIDoc) Search(uri core.URI, pos core.Position, t reflect.Type) (r core.Searcher)
- func (doc *APIDoc) XMLNamespace(prefix string) *XMLNamespace
- type APIDocVersionAttribute
- type Attribute
- type Bool
- type BoolAttribute
- type CData
- type Callback
- type Contact
- type Content
- type Date
- type DateAttribute
- type Definition
- type Definitioner
- type Element
- type Enum
- type Example
- type ExampleValue
- type Link
- type MethodAttribute
- type Number
- type NumberAttribute
- type Param
- type Path
- type Reference
- type Referencer
- type Request
- type Richtext
- type Server
- type ServerValue
- type StatusAttribute
- type Tag
- type TagValue
- type TypeAttribute
- type VersionAttribute
- type XML
- type XMLNamespace
Constants ¶
const ( // Version 文档规范的版本 Version = "6.1.0" // MajorVersion 文档规范的主版本信息 MajorVersion = "v6" )
const ( TypeNone = "" // 空值表示不输出任何内容,仅用于 Request TypeBool = "bool" TypeObject = "object" TypeNumber = "number" TypeString = "string" TypeInt = "number.int" TypeFloat = "number.float" TypeEmail = "string.email" TypeURL = "string.url" TypeImage = "string.image" // 表示图片的 URL TypeDate = "string.date" // RFC3339 full-date TypeTime = "string.time" // RFC3339 full-time TypeDateTime = "string.date-time" // RFC3339 full-date + full-time )
表示支持的各种数据类型
const ( RichtextTypeHTML = "html" RichtextTypeMarkdown = "markdown" )
富文本可用的类型
const ( DateFormat = "2006-01-02" // 对应 TypeDate TimeFormat = "15:04:05Z07:00" // 对应 TypeTime DateTimeFormat = time.RFC3339 // 对应 TypeDateTime )
几种与时间类型相关的格式
Variables ¶
This section is empty.
Functions ¶
Types ¶
type API ¶
type API struct { xmlenc.BaseTag RootName struct{} `apidoc:"api,meta,usage-api"` Version *VersionAttribute `apidoc:"version,attr,usage-api-version,omitempty"` Method *MethodAttribute `apidoc:"method,attr,usage-api-method"` ID *Attribute `apidoc:"id,attr,usage-api-id,omitempty"` Path *Path `apidoc:"path,elem,usage-api-path"` Summary *Attribute `apidoc:"summary,attr,usage-api-summary,omitempty"` Description *Richtext `apidoc:"description,elem,usage-api-description,omitempty"` Requests []*Request `apidoc:"request,elem,usage-api-requests,omitempty"` // 不同的 mimetype 可能会定义不同 Responses []*Request `apidoc:"response,elem,usage-api-responses,omitempty"` Callback *Callback `apidoc:"callback,elem,usage-api-callback,omitempty"` Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-api-deprecated,omitempty"` Headers []*Param `apidoc:"header,elem,usage-api-headers,omitempty"` Tags []*TagValue `apidoc:"tag,elem,usage-api-tags,omitempty"` Servers []*ServerValue `apidoc:"server,elem,usage-api-servers,omitempty"` // contains filtered or unexported fields }
API 表示 <api> 顶层元素
type APIDoc ¶
type APIDoc struct { xmlenc.BaseTag RootName struct{} `apidoc:"apidoc,meta,usage-apidoc"` APIDoc *APIDocVersionAttribute `apidoc:"apidoc,attr,usage-apidoc-apidoc,omitempty"` // 文档格式的版本号 Lang *Attribute `apidoc:"lang,attr,usage-apidoc-lang,omitempty"` // 区域信息,应该使用 BCP47 指定的格式 Logo *Attribute `apidoc:"logo,attr,usage-apidoc-logo,omitempty"` XMLNamespaces []*XMLNamespace `apidoc:"xml-namespace,elem,usage-apidoc-xml-namespaces,omitempty"` Created *DateAttribute `apidoc:"created,attr,usage-apidoc-created,omitempty"` // 生成时间 Version *VersionAttribute `apidoc:"version,attr,usage-apidoc-version,omitempty"` Title *Element `apidoc:"title,elem,usage-apidoc-title"` Description *Richtext `apidoc:"description,elem,usage-apidoc-description,omitempty"` // 说明内容 Contact *Contact `apidoc:"contact,elem,usage-apidoc-contact,omitempty"` // 团队的联系方式 License *Link `apidoc:"license,elem,usage-apidoc-license,omitempty"` // 版权信息 Tags []*Tag `apidoc:"tag,elem,usage-apidoc-tags,omitempty"` // 标签列表 Servers []*Server `apidoc:"server,elem,usage-apidoc-servers,omitempty"` // 服务器列表 APIs []*API `apidoc:"api,elem,usage-apidoc-apis,omitempty"` // API 列表 Headers []*Param `apidoc:"header,elem,usage-apidoc-headers,omitempty"` // 公共报头 Responses []*Request `apidoc:"response,elem,usage-apidoc-responses,omitempty"` // 所有 API 都有可能的返回内容 Mimetypes []*Element `apidoc:"mimetype,elem,usage-apidoc-mimetypes"` // 所有接口都支持的 mimetypes }
APIDoc 对应 apidoc 元素
func (*APIDoc) Parse ¶
func (doc *APIDoc) Parse(h *core.MessageHandler, b core.Block)
Parse 将注释块的内容添加到当前文档
func (*APIDoc) ParseBlocks ¶
func (doc *APIDoc) ParseBlocks(h *core.MessageHandler, g func(chan core.Block))
ParseBlocks 从多个 core.Block 实例中解析文档内容
g 必须是一个阻塞函数,直到所有代码块都写入参数之后,才能返回。
func (*APIDoc) Search ¶ added in v7.2.0
Search 搜索符合条件的对象并返回
从 doc 中查找符合符合 pos 定位的最小对象,且该对象必须实现了 t 类型。 如果不存在则返回 nil。t 必须是一个接口。
func (*APIDoc) XMLNamespace ¶
func (doc *APIDoc) XMLNamespace(prefix string) *XMLNamespace
XMLNamespace 获取指定前缀名称的命名空间
type APIDocVersionAttribute ¶
type APIDocVersionAttribute Attribute
APIDocVersionAttribute 版本号属性,同时对版本号进行比较
func (*APIDocVersionAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*APIDocVersionAttribute) EncodeXMLAttr ¶
func (a *APIDocVersionAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type Attribute ¶
type Attribute struct { xmlenc.BaseAttribute Value xmlenc.String `apidoc:"-"` RootName struct{} `apidoc:"string,meta,usage-string"` }
Attribute 表示 XML 属性
func (*Attribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*Attribute) EncodeXMLAttr ¶
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type BoolAttribute ¶
type BoolAttribute struct { xmlenc.BaseAttribute Value Bool `apidoc:"-"` RootName struct{} `apidoc:"bool,meta,usage-bool"` }
BoolAttribute 表示布尔值类型的属性
func (*BoolAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*BoolAttribute) EncodeXMLAttr ¶
func (b *BoolAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type CData ¶
type CData struct { xmlenc.BaseTag Value xmlenc.String `apidoc:"-"` RootName struct{} `apidoc:"string,meta,usage-string"` }
CData 表示 XML 的 CDATA 数据
type Callback ¶
type Callback struct { xmlenc.BaseTag RootName struct{} `apidoc:"callback,meta,usage-callback"` Method *MethodAttribute `apidoc:"method,attr,usage-callback-method"` Path *Path `apidoc:"path,elem,usage-callback-path,omitempty"` Summary *Attribute `apidoc:"summary,attr,usage-callback-summary,omitempty"` Description *Richtext `apidoc:"description,elem,usage-callback-description,omitempty"` Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-callback-deprecated,omitempty"` Responses []*Request `apidoc:"response,elem,usage-callback-responses,omitempty"` Requests []*Request `apidoc:"request,elem,usage-callback-requests"` // 至少一个 Headers []*Param `apidoc:"header,elem,usage-callback-headers,omitempty"` }
Callback 描述回调信息
type Contact ¶
type Contact struct { xmlenc.BaseTag RootName struct{} `apidoc:"contact,meta,usage-contact"` Name *Attribute `apidoc:"name,attr,usage-contact-name"` URL *Element `apidoc:"url,elem,usage-contact-url,omitempty"` Email *Element `apidoc:"email,elem,usage-contact-email,omitempty"` }
Contact 描述联系方式
type Content ¶
type Content struct { xmlenc.Base Value string `apidoc:"-"` RootName struct{} `apidoc:"string,meta,usage-string"` }
Content 表示一段普通的 XML 元素内容
type DateAttribute ¶
type DateAttribute struct { xmlenc.BaseAttribute Value Date `apidoc:"-"` RootName struct{} `apidoc:"date,meta,usage-date"` }
DateAttribute 日期属性
func (*DateAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*DateAttribute) EncodeXMLAttr ¶
func (d *DateAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type Definition ¶ added in v7.2.0
Definition 指向父对象的实际定义数据
type Definitioner ¶ added in v7.2.0
type Definitioner interface { core.Searcher Definition() *Definition }
Definitioner 包含了 Definition 数据需要实现的接口
type Element ¶
type Element struct { xmlenc.BaseTag Content Content `apidoc:",content"` RootName struct{} `apidoc:"string,meta,usage-string"` }
Element 定义不包含子元素和属性的基本的 XML 元素
type Enum ¶
type Enum struct { xmlenc.BaseTag RootName struct{} `apidoc:"enum,meta,usage-enum"` Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-enum-deprecated,omitempty"` Value *Attribute `apidoc:"value,attr,usage-enum-value"` Summary *Attribute `apidoc:"summary,attr,usage-enum-summary,omitempty"` Description *Richtext `apidoc:"description,elem,usage-enum-description,omitempty"` }
Enum 表示枚举值
type Example ¶
type Example struct { xmlenc.BaseTag RootName struct{} `apidoc:"example,meta,usage-example"` Mimetype *Attribute `apidoc:"mimetype,attr,usage-example-mimetype"` Content *ExampleValue `apidoc:",cdata,usage-example-content"` Summary *Attribute `apidoc:"summary,attr,usage-example-summary,omitempty"` }
Example 示例代码
type ExampleValue ¶
type ExampleValue CData
ExampleValue 示例代码的内容
func (*ExampleValue) EncodeXML ¶
func (v *ExampleValue) EncodeXML() (string, error)
EncodeXML Encoder.EncodeXML
示例代码的内容,会在此处去掉其前导的空格
type Link ¶
type Link struct { xmlenc.BaseTag RootName struct{} `apidoc:"link,meta,usage-link"` Text *Attribute `apidoc:"text,attr,usage-link-text"` URL *Attribute `apidoc:"url,attr,usage-link-url"` }
Link 表示一个链接
type MethodAttribute ¶
type MethodAttribute Attribute
MethodAttribute 表示请求方法
func (*MethodAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*MethodAttribute) EncodeXMLAttr ¶
func (a *MethodAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type NumberAttribute ¶
type NumberAttribute struct { xmlenc.BaseAttribute Value Number `apidoc:"-"` RootName struct{} `apidoc:"number,meta,usage-number"` }
NumberAttribute 表示数值类型的属性
func (*NumberAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*NumberAttribute) EncodeXMLAttr ¶
func (num *NumberAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
func (*NumberAttribute) FloatValue ¶
func (num *NumberAttribute) FloatValue() float64
FloatValue 返回当前属性实际表示的值
type Param ¶
type Param struct { xmlenc.BaseTag RootName struct{} `apidoc:"param,meta,usage-param"` XML Name *Attribute `apidoc:"name,attr,usage-param-name"` Type *TypeAttribute `apidoc:"type,attr,usage-param-type"` Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-param-deprecated,omitempty"` Default *Attribute `apidoc:"default,attr,usage-param-default,omitempty"` Optional *BoolAttribute `apidoc:"optional,attr,usage-param-optional,omitempty"` Array *BoolAttribute `apidoc:"array,attr,usage-param-array,omitempty"` Items []*Param `apidoc:"param,elem,usage-param-items,omitempty"` Summary *Attribute `apidoc:"summary,attr,usage-param-summary,omitempty"` Enums []*Enum `apidoc:"enum,elem,usage-param-enums,omitempty"` Description *Richtext `apidoc:"description,elem,usage-param-description,omitempty"` // 数组参数是否展开 // // 数组可以有以下两种展示方式: // 1. k=1&k=2 // 2. k=1,2 // 1 为默认方式,ArrayStyle 为 true,则展示为第二种方式 // 该参数目前仅在查询参数中启作用 ArrayStyle *BoolAttribute `apidoc:"array-style,attr,usage-param-array-style,omitempty"` }
Param 表示参数类型
type Path ¶
type Path struct { xmlenc.BaseTag RootName struct{} `apidoc:"path,meta,usage-path"` Path *Attribute `apidoc:"path,attr,usage-path-path"` Params []*Param `apidoc:"param,elem,usage-path-params,omitempty"` Queries []*Param `apidoc:"query,elem,usage-path-queries,omitempty"` }
Path 路径信息
type Referencer ¶ added in v7.2.0
Referencer 包含了 Reference 数据需要实现的接口
type Request ¶
type Request struct { xmlenc.BaseTag RootName struct{} `apidoc:"request,meta,usage-request"` XML // 一般无用,但是用于描述 XML 对象时,可以用来表示顶层元素的名称 Name *Attribute `apidoc:"name,attr,usage-request-name,omitempty"` Type *TypeAttribute `apidoc:"type,attr,usage-request-type,omitempty"` Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-request-deprecated,omitempty"` Enums []*Enum `apidoc:"enum,elem,usage-request-enums,omitempty"` Array *BoolAttribute `apidoc:"array,attr,usage-request-array,omitempty"` Items []*Param `apidoc:"param,elem,usage-request-items,omitempty"` Summary *Attribute `apidoc:"summary,attr,usage-request-summary,omitempty"` Status *StatusAttribute `apidoc:"status,attr,usage-request-status,omitempty"` Mimetype *Attribute `apidoc:"mimetype,attr,usage-request-mimetype,omitempty"` Examples []*Example `apidoc:"example,elem,usage-request-examples,omitempty"` Headers []*Param `apidoc:"header,elem,usage-request-headers,omitempty"` // 当前独有的报头,公用的可以放在 API 中 Description *Richtext `apidoc:"description,elem,usage-request-description,omitempty"` }
Request 请求内容
type Richtext ¶
type Richtext struct { xmlenc.BaseTag RootName struct{} `apidoc:"richtext,meta,usage-richtext"` Type *Attribute `apidoc:"type,attr,usage-richtext-type"` // 文档类型,可以是 html 或是 markdown Text *CData `apidoc:",cdata,usage-richtext-text"` }
Richtext 富文本内容
type Server ¶
type Server struct { xmlenc.BaseTag RootName struct{} `apidoc:"server,meta,usage-server"` Name *Attribute `apidoc:"name,attr,usage-server-name"` // 字面名称,需要唯一 URL *Attribute `apidoc:"url,attr,usage-server-url"` Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-server-deprecated,omitempty"` Summary *Attribute `apidoc:"summary,attr,usage-server-summary,omitempty"` Description *Richtext `apidoc:"description,elem,usage-server-description,omitempty"` // contains filtered or unexported fields }
Server 服务信息
func (*Server) References ¶ added in v7.2.0
References impl Referencer
type ServerValue ¶ added in v7.2.0
type ServerValue struct { xmlenc.BaseTag Content Content `apidoc:",content"` RootName struct{} `apidoc:"string,meta,usage-string"` // contains filtered or unexported fields }
ServerValue api.server 的类型
func (*ServerValue) Definition ¶ added in v7.2.0
func (s *ServerValue) Definition() *Definition
Definition Definitioner.Definition
type StatusAttribute ¶
type StatusAttribute NumberAttribute
StatusAttribute 状态码的 XML 属性
func (*StatusAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*StatusAttribute) EncodeXMLAttr ¶
func (a *StatusAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type Tag ¶
type Tag struct { xmlenc.BaseTag RootName struct{} `apidoc:"tag,meta,usage-tag"` Name *Attribute `apidoc:"name,attr,usage-tag-name"` // 标签的唯一 ID Title *Attribute `apidoc:"title,attr,usage-tag-title"` // 显示的名称 Deprecated *VersionAttribute `apidoc:"deprecated,attr,usage-tag-deprecated,omitempty"` // contains filtered or unexported fields }
Tag 标签内容
func (*Tag) References ¶ added in v7.2.0
References impl Referencer
type TagValue ¶ added in v7.2.0
type TagValue struct { xmlenc.BaseTag Content Content `apidoc:",content"` RootName struct{} `apidoc:"string,meta,usage-string"` // contains filtered or unexported fields }
TagValue api.tag 的类型
func (*TagValue) Definition ¶ added in v7.2.0
func (s *TagValue) Definition() *Definition
Definition Definitioner.Definition
type TypeAttribute ¶
type TypeAttribute struct { xmlenc.BaseAttribute Value xmlenc.String `apidoc:"-"` RootName struct{} `apidoc:"type,meta,usage-type"` }
TypeAttribute 表示方法类型属性
func (*TypeAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*TypeAttribute) EncodeXMLAttr ¶
func (a *TypeAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type VersionAttribute ¶
type VersionAttribute struct { xmlenc.BaseAttribute Value xmlenc.String `apidoc:"-"` RootName struct{} `apidoc:"version,meta,usage-version"` }
VersionAttribute 表示版本号属性
func (*VersionAttribute) DecodeXMLAttr ¶
DecodeXMLAttr AttrDecoder.DecodeXMLAttr
func (*VersionAttribute) EncodeXMLAttr ¶
func (a *VersionAttribute) EncodeXMLAttr() (string, error)
EncodeXMLAttr AttrEncoder.EncodeXMLAttr
type XML ¶
type XML struct { XMLAttr *BoolAttribute `apidoc:"xml-attr,attr,usage-xml-attr,omitempty"` // 作为父元素的 XML 属性存在 XMLExtract *BoolAttribute `apidoc:"xml-extract,attr,usage-xml-extract,omitempty"` // 提取当前内容作为父元素的内容 XMLCData *BoolAttribute `apidoc:"xml-cdata,attr,usage-xml-cdata,omitempty"` // 内容为 CDATA XMLNSPrefix *Attribute `apidoc:"xml-ns-prefix,attr,usage-xml-prefix,omitempty"` // 命名空间前缀 XMLWrapped *Attribute `apidoc:"xml-wrapped,attr,usage-xml-wrapped,omitempty"` // 如果当前元素是数组,是否将其包含在 wrapped 中 }
XML 仅作用于 XML 的几个属性
type XMLNamespace ¶
type XMLNamespace struct { xmlenc.BaseTag RootName struct{} `apidoc:"xml-namespace,meta,usage-xml-namespace"` Prefix *Attribute `apidoc:"prefix,attr,usage-xml-namespace-prefix,omitempty"` URN *Attribute `apidoc:"urn,attr,usage-xml-namespace-urn"` }
XMLNamespace 定义命名空间的相关属性
func (*XMLNamespace) Sanitize ¶
func (ns *XMLNamespace) Sanitize(p *xmlenc.Parser)
Sanitize 检测内容是否合法