doc

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"`
	Description Richtext   `xml:"description,omitempty"`
	Requests    []*Request `xml:"request"` // 不同的 mimetype 可能会定义不同
	Responses   []*Request `xml:"response"`
	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
}

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"`
}

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

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"`
	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"`
	// contains filtered or unexported fields
}

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"`
}

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

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

type Method string

type Param struct {
	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"`
}

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

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

	Type        Type       `xml:"type,attr"` // Request 中默认为 None
	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"`
	Examples    []*Example `xml:"example,omitempty"`
	Headers     []*Param   `xml:"header,omitempty"` // 当前独有的报头，公用的可以放在 API 中
	Description Richtext   `xml:"description,omitempty"`
}

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

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"`
}

type Status int

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

type Type string

type Version string