doc

package
v6.0.1 Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2020 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package doc 文档格式

Index

Constants

View Source 
const (
	RichtextTypeHTML     = "html"
	RichtextTypeMarkdown = "markdown"
)

富文本可用的类型

View Source 
const (
	None   Type = ""
	Bool        = "bool"
	Object      = "object"
	Number      = "number"
	String      = "string"
)

表示支持的各种数据类型

Variables

This section is empty.

Functions

func Valid 

func Valid(content []byte) error

Valid 验证文档内容的正确性

Types

type API 

type API struct {
	XMLName     struct{}   `xml:"api"`
	Version     Version    `xml:"version,attr,omitempty"`
	Method      Method     `xml:"method,attr"`
	ID          string     `xml:"id,attr,omitempty"`
	Path        *Path      `xml:"path"`
	Summary     string     `xml:"summary,attr,omitempty"`
	Description Richtext   `xml:"description,omitempty"`
	Requests    []*Request `xml:"request,omitempty"` // 不同的 mimetype 可能会定义不同
	Responses   []*Request `xml:"response,omitempty"`
	Callback    *Callback  `xml:"callback,omitempty"`
	Deprecated  Version    `xml:"deprecated,attr,omitempty"`
	Headers     []*Param   `xml:"header,omitempty"`

	Tags    []string `xml:"tag,omitempty"`
	Servers []string `xml:"server,omitempty"`
	// contains filtered or unexported fields
}

API 表示 <api> 顶层元素 

<api method="GET" version="1.1.1" id="get-user">
    <path path="/users/{id}">
        <param name="id" type="number" summary="summary" />
    </path>
    <tag>tag1</tag>
    <server>admin</server>
    ...
</api>

func (*API) UnmarshalXML 

func (api *API) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML 实现 xml.Unmarshaler 接口

type Callback 

type Callback struct {
	Method      Method     `xml:"method,attr"`
	Path        *Path      `xml:"path,omitempty"`
	Summary     string     `xml:"summary,attr,omitempty"`
	Description Richtext   `xml:"description,omitempty"`
	Deprecated  Version    `xml:"deprecated,attr,omitempty"`
	Reference   string     `xml:"ref,attr,omitempty"`
	Responses   []*Request `xml:"response,omitempty"`
	Requests    []*Request `xml:"request"` // 至少一个
	Headers     []*Param   `xml:"header,omitempty"`
}

Callback 回调函数的定义 

<Callback deprecated="1.1.1" method="GET">
     <request status="200" mimetype="json" type="object">
         <param name="name" type="string" />
         <param name="sex" type="string">
             <enum value="male" summary="male" />
             <enum value="female" summary="female" />
         </param>
         <param name="age" type="number" />
     </request>
 </Callback>

func (*Callback) UnmarshalXML 

func (c *Callback) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Contact 

type Contact struct {
	Name  string `xml:"name,attr"`
	URL   string `xml:"url,omitempty"`
	Email string `xml:"email,omitempty"`
}

Contact 描述联系方式 

<contact name="name">
    <url>https://example.com</url>
    <email>name@example.com</email>
</contact>

func (*Contact) UnmarshalXML 

func (c *Contact) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Doc 

type Doc struct {
	XMLName struct{} `xml:"apidoc"`

	// 程序的版本号
	//
	// 同时也作为文档格式的版本号。客户端可以依此值确定文档格式。
	// 仅用于输出，文档中不需要指定此值。
	APIDoc string `xml:"apidoc,attr,omitempty"`

	// 文档内容的区域信息
	// 如果存在此值，客户端应该尽量根据此值显示相应的界面语言。
	Lang string `xml:"lang,attr,omitempty"`

	//
	// 如果采用默认的 xsl 转换，会替换掉页面上的图标和 favicon 图标
	Logo string `xml:"logo,attr,omitempty"`

	Created     string    `xml:"created,attr,omitempty"` // 文档的生成时间
	Version     Version   `xml:"version,attr,omitempty"` // 文档的版本
	Title       string    `xml:"title"`
	Description Richtext  `xml:"description,omitempty"`
	Contact     *Contact  `xml:"contact,omitempty"`
	License     *Link     `xml:"license,omitempty"` // 版本信息
	Tags        []*Tag    `xml:"tag,omitempty"`     // 所有的标签
	Servers     []*Server `xml:"server,omitempty"`
	Apis        []*API    `xml:"api,omitempty"`

	// 表示所有 API 都有可能返回的内容
	Responses []*Request `xml:"response,omitempty"`

	// 表示所有接口都支持的文档类型
	Mimetypes []string `xml:"mimetype"`
	// contains filtered or unexported fields
}

Doc 文档

func New 

func New() *Doc

New 返回 Doc 实例

func (*Doc) FromXML 

func (doc *Doc) FromXML(file string, line int, data []byte) error

FromXML 从 XML 字符串初始化当前的实例

file 和 line 仅用于在出错时定位错误的位置，并无其它用处； data 表示 XML 内容。

func (*Doc) NewAPI 

func (doc *Doc) NewAPI(file string, line int, data []byte) error

NewAPI 从 data 中解析新的 API 对象

func (*Doc) Sanitize 

func (doc *Doc) Sanitize() error

Sanitize 检测内容是否合法

func (*Doc) UnmarshalXML 

func (doc *Doc) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML 实现 xml.Unmarshaler 接口

返回的错误信息都为 message.SyntaxError 实例

type Enum 

type Enum struct {
	Deprecated  Version  `xml:"deprecated,attr,omitempty"`
	Value       string   `xml:"value,attr"`
	Summary     string   `xml:"summary,attr,omitempty"`
	Description Richtext `xml:"description,omitempty"`
}

Enum 表示枚举值 

<enum value="male" summary="男性" />
<enum value="female"><description type="html"><p>女性</p></description></enum>

func (*Enum) UnmarshalXML 

func (e *Enum) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Example 

type Example struct {
	Mimetype    string   `xml:"mimetype,attr"`
	Content     string   `xml:",cdata"`
	Summary     string   `xml:"summary,attr,omitempty"`
	Description Richtext `xml:"description,omitempty"`
}

Example 示例代码

func (*Example) UnmarshalXML 

func (e *Example) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler 

type Link struct {
	Text string `xml:"text,attr"`
	URL  string `xml:"url,attr"`
}

Link 表示一个链接 

<link url="https://example.com" text="text" />

func (*Link) UnmarshalXML 

func (l *Link) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Method 

type Method string

Method 表示请求方法

func (Method) MarshalXML 

func (m Method) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML xml.Marshaler

func (Method) MarshalXMLAttr 

func (m Method) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr xml.MarshalerAttr

func (*Method) UnmarshalXML 

func (m *Method) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

func (*Method) UnmarshalXMLAttr 

func (m *Method) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr xml.UnmarshalerAttr

type Param 

type Param struct {
	XML
	Name        string   `xml:"name,attr"`
	Type        Type     `xml:"type,attr"`
	Deprecated  Version  `xml:"deprecated,attr,omitempty"`
	Default     string   `xml:"default,attr,omitempty"`
	Optional    bool     `xml:"optional,attr,omitempty"`
	Array       bool     `xml:"array,attr,omitempty"`
	Items       []*Param `xml:"param,omitempty"`
	Reference   string   `xml:"ref,attr,omitempty"`
	Summary     string   `xml:"summary,attr,omitempty"`
	Enums       []*Enum  `xml:"enum,omitempty"`
	Description Richtext `xml:"description,omitempty"`
}

Param 表示参数类型 

<param name="user" deprecated="1.1.1" type="object" array="true">
    <param name="name" type="string" />
    <param name="sex" type="string">
        <enum value="male" summary="male" />
        <enum value="female" summary="female" />
    </param>
    <param name="age" type="number" />
</param>

func (*Param) IsEnum 

func (p *Param) IsEnum() bool

IsEnum 是否为一个枚举类型

func (*Param) UnmarshalXML 

func (p *Param) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Path 

type Path struct {
	Path      string   `xml:"path,attr"`
	Params    []*Param `xml:"param,omitempty"`
	Queries   []*Param `xml:"query,omitempty"`
	Reference string   `xml:"ref,attr,omitempty"`
}

Path 路径信息 

<path path="/users/{id}">
    <param name="id" type="number" summary="summary" />
    <query name="page" type="number" summary="page" default="1" />
</path>

func (*Path) UnmarshalXML 

func (p *Path) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Request 

type Request struct {
	XML

	// 一般无用，但是用于描述 XML 对象时，可以用来表示顶层元素的名称
	Name string `xml:"name,attr,omitempty"`

	Type        Type       `xml:"type,attr,omitempty"`
	Deprecated  Version    `xml:"deprecated,attr,omitempty"`
	Enums       []*Enum    `xml:"enum,omitempty"`
	Array       bool       `xml:"array,attr,omitempty"`
	Items       []*Param   `xml:"param,omitempty"`
	Reference   string     `xml:"ref,attr,omitempty"`
	Summary     string     `xml:"summary,attr,omitempty"`
	Status      Status     `xml:"status,attr,omitempty"`
	Mimetype    string     `xml:"mimetype,attr,omitempty"`
	Examples    []*Example `xml:"example,omitempty"`
	Headers     []*Param   `xml:"header,omitempty"` // 当前独有的报头，公用的可以放在 API 中
	Description Richtext   `xml:"description,omitempty"`
}

Request 请求内容

func (*Request) IsEnum 

func (r *Request) IsEnum() bool

IsEnum 是否为枚举值

func (*Request) Param 

func (r *Request) Param() *Param

Param 转换成 Param 对象

Request 可以说是 Param 的超级，两者在大部分情况下能用。

func (*Request) UnmarshalXML 

func (r *Request) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Richtext 

type Richtext struct {
	Type string `xml:"type,attr,omitempty"` // 文档类型，可以是 html 或是 markdown
	Text string `xml:",cdata"`
}

Richtext 富文本内容

func (Richtext) MarshalXML 

func (text Richtext) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML xml.Marshaler

func (*Richtext) UnmarshalXML 

func (text *Richtext) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML 实现 xml.Unmarshaler

type Server 

type Server struct {
	Name        string   `xml:"name,attr"` // 字面名称，需要唯一
	URL         string   `xml:"url,attr"`
	Deprecated  Version  `xml:"deprecated,attr,omitempty"`
	Summary     string   `xml:"summary,attr,omitempty"`
	Description Richtext `xml:"description,omitempty"`
}

Server 服务信息 

<server name="tag1" deprecated="1.1.1" url="api.example.com/admin" summary="description" />

func (*Server) UnmarshalXML 

func (srv *Server) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Status 

type Status int

Status 表示 HTTP 状态码

func (Status) MarshalXML 

func (s Status) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML xml.Marshaler

func (Status) MarshalXMLAttr 

func (s Status) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr xml.MarshalerAttr

func (Status) String 

func (s Status) String() string

String fmt.Stringer

func (*Status) UnmarshalXML 

func (s *Status) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

func (*Status) UnmarshalXMLAttr 

func (s *Status) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr xml.UnmarshalerAttr

type Tag 

type Tag struct {
	Name       string  `xml:"name,attr"`  // 标签的唯一 ID
	Title      string  `xml:"title,attr"` // 显示的名称
	Deprecated Version `xml:"deprecated,attr,omitempty"`
}

Tag 标签内容 

<tag name="tag1" deprecated="1.1.1" />

func (*Tag) UnmarshalXML 

func (t *Tag) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

type Type 

type Type string

Type 表示参数类型

func (Type) MarshalXML 

func (t Type) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML xml.Marshaler

func (Type) MarshalXMLAttr 

func (t Type) MarshalXMLAttr(name xml.Name) (attr xml.Attr, err error)

MarshalXMLAttr xml.MarshalerAttr

func (*Type) UnmarshalXML 

func (t *Type) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

func (*Type) UnmarshalXMLAttr 

func (t *Type) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr xml.UnmarshalerAttr

type Version 

type Version string

Version 版本号

func (Version) MarshalXML 

func (v Version) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML xml.Marshaler

func (Version) MarshalXMLAttr 

func (v Version) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr xml.MarshalerAttr

func (*Version) UnmarshalXML 

func (v *Version) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML xml.Unmarshaler

func (*Version) UnmarshalXMLAttr 

func (v *Version) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr xml.UnmarshalerAttr

type XML 

type XML struct {
	XMLAttr     bool   `xml:"xml-attr,attr,omitempty"`      // 作为父元素的 XML 属性存在
	XMLExtract  bool   `xml:"xml-extract,attr,omitempty"`   // 提取当前内容作为父元素的内容
	XMLNS       string `xml:"xml-ns,attr,omitempty"`        // 命名空间
	XMLNSPrefix string `xml:"xml-ns-prefix,attr,omitempty"` // 命名空间前缀
	XMLWrapped  string `xml:"xml-wrapped,attr,omitempty"`   // 如果当前元素是数组，是否将其包含在 wrapped 中
}

XML 仅作用于 XML 的几个属性

Source Files

View all Source files

Directories

Path Synopsis
Package doctest 提供了一个合法的 doc.Doc 对象
 Package doctest 提供了一个合法的 doc.Doc 对象

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.