doc

Documentation

Overview

Package doc 表示最终解析出来的文档结果。

Index

• Constants
• type API
• type Body
• type Callback
• type Contact
• type Doc
  • func Parse(ctx context.Context, h *errors.Handler, input ...*options.Input) (*Doc, error)
• type Example
• type Header
• type Link
• type Markdown
• type Param
• type Request
• type Response
• type Schema
• type Server
• type Tag

Constants

const (
	Null    = "null"
	Bool    = "boolean"
	Object  = "object"
	Array   = "array"
	Number  = "number"
	String  = "string"
	Integer = "integer"
)

Schema.Type 的值枚举

Types

type API

type API struct {
	Path        string    `yaml:"path" json:"path"`
	Description Markdown  `yaml:"description,omitempty" json:"description,omitempty"`
	Tags        []string  `yaml:"tags,omitempty" json:"tags,omitempty"`
	Deprecated  string    `yaml:"deprecated,omitempty" json:"deprecated,omitempty"`
	Servers     []string  `yaml:"servers" json:"servers"`
	Callback    *Callback `yaml:"callback,omitempty" json:"callback,omitempty"`
	// contains filtered or unexported fields
}

API 表示单个 API 文档

type Body

type Body struct {
	Mimetype string     `yaml:"mimetype,omitempty" json:"mimetype,omitempty"`
	Headers  []*Header  `yaml:"headers,omitempty" json:"headers,omitempty"`
	Type     *Schema    `yaml:"type" json:"type"`
	Examples []*Example `yaml:"examples,omitempty" json:"examples,omitempty"`
}

Body 表示请求和返回的共有内容

type Callback

type Callback struct {
	// contains filtered or unexported fields
}

Callback 回调内容

@apiCallback GET
@apiquery ...
@apiparam ...

type Contact

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

Contact 描述联系方式

type Doc

type Doc struct {
	// 以下字段不对应具体的标签
	APIDoc  string        `yaml:"apidoc" json:"apidoc"`   // 当前的程序版本
	Elapsed time.Duration `yaml:"elapsed" json:"elapsed"` // 文档解析用时

	Title   string    `yaml:"title" json:"title"`
	Content Markdown  `yaml:"content,omitempty" json:"content,omitempty"`
	Contact *Contact  `yaml:"contact,omitempty" json:"contact,omitempty"`
	License *Link     `yaml:"license,omitempty" json:"license,omitempty" ` // 版本信息
	Version string    `yaml:"version,omitempty" json:"version,omitempty"`  // 文档的版本
	Tags    []*Tag    `yaml:"tags,omitempty" json:"tags,omitempty"`        // 所有的标签
	Servers []*Server `yaml:"servers,omitempty" json:"servers,omitempty"`

	Apis []*API `yaml:"apis" json:"apis"`
	// contains filtered or unexported fields
}

Doc 文档

func Parse

func Parse(ctx context.Context, h *errors.Handler, input ...*options.Input) (*Doc, error)

Parse 分析从 block 中获取的代码块。并填充到 Doc 中

当所有的代码块已经放入 Block 之后，Block 会被关闭。

所有与解析有关的错误均通过 h 输出。而其它错误，比如参数问题等，通过返回参数返回。

type Example

type Example struct {
	Mimetype string `yaml:"mimetype" json:"mimetype"`
	Summary  string `yaml:"summary,omitempty" json:"summary,omitempty"`
	Value    string `yaml:"value" json:"value"` // 示例内容
}

Example 示例

type Header

type Header struct {
	Name     string `yaml:"name" json:"name"`                             // 参数名称
	Summary  string `yaml:"summary" json:"summary"`                       // 参数介绍
	Optional bool   `yaml:"optional,omitempty" json:"optional,omitempty"` // 是否可以为空
}

Header 报头

type Link

type Link struct {
	Text string `yaml:"text" json:"text"`
	URL  string `yaml:"url" json:"url"`
}

Link 表示一个链接

type Markdown

type Markdown string

Markdown 表示可以使用 markdown 文档

type Param

type Param struct {
	Name     string  `yaml:"name" json:"name"`                             // 参数名称
	Type     *Schema `yaml:"type" json:"type"`                             // 类型
	Summary  string  `yaml:"summary" json:"summary"`                       // 参数介绍
	Optional bool    `yaml:"optional,omitempty" json:"optional,omitempty"` // 是否为可选参数
}

Param 简单参数的描述，比如查询参数等

type Request

type Request = Body

Request 表示用户请求所表示的数据。

type Response

type Response struct {
	Body
	Status int `yaml:"status" json:"status"`
}

Response 表示一次请求或是返回的数据。

type Schema

type Schema struct {
	Type string        `json:"type,omitempty" yaml:"type,omitempty"`
	Enum []interface{} `json:"enum,omitempty" yaml:"enum,omitempty"`

	// 数值验证
	MultipleOf       int  `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Maximum          int  `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum bool `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum          int  `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	ExclusiveMinimum bool `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`

	// 字符串验证
	MaxLength int    `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MinLength int    `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	Pattern   string `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// 数组验证
	Items           *Schema `json:"items,omitempty" yaml:"items,omitempty"`
	AdditionalItems *Schema `json:"additionalItems,omitempty" ymal:"additionalItems,omitempty"`
	MaxItems        int     `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinItems        int     `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	UniqueItems     bool    `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	Contains        *Schema `json:"contains,omitempty" yaml:"contains,omitempty"`

	// 对象验证
	MaxProperties        int                `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	MinProperties        int                `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`
	Required             []string           `json:"required,omitempty" yaml:"required,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
	PatternProperties    map[string]*Schema `json:"patternProperties,omitempty" yaml:"patternProperties,omitempty"`
	AdditionalProperties map[string]*Schema `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	Dependencies         map[string]*Schema `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`
	PropertyNames        *Schema            `json:"propertyNames,omitempty" yaml:"propertyNames,omitempty"`

	AllOf []*Schema `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	AnyOf []*Schema `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`
	OneOf []*Schema `json:"oneOf,omitempty" yaml:"oneOf,omitempty"`
	Not   *Schema   `json:"not,omitempty" yaml:"not,omitempty"`

	// 可复用对象的定义
	Definitions map[string]*Schema `json:"definitions,omitempty" yaml:"definitions,omitempty"`
	Ref         string             `json:"$ref,omitempty" yaml:"$ref,omitempty"`

	Title       string      `json:"title,omitempty" yaml:"title,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Default     interface{} `json:"default,omitempty" yaml:"default,omitempty"`
	ReadOnly    bool        `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	WriteOnly   bool        `json:"writeOnly,omitempty" yaml:"writeOnly,omitempty"`
}

Schema 简化的 JSON Schema https://json-schema.org/latest/json-schema-validation.html

type Server

type Server struct {
	Name        string   `yaml:"name" json:"name"` // 字面名称，需要唯一
	URL         string   `yaml:"url" json:"url"`
	Description Markdown `yaml:"description,omitempty" json:"description,omitempty"` // 具体描述
}

Server 服务信息

type Tag

type Tag struct {
	Name        string   `yaml:"name" json:"name"`                                   // 字面名称，需要唯一
	Description Markdown `yaml:"description,omitempty" json:"description,omitempty"` // 具体描述
}

Tag 标签内容