Documentation
¶
Overview ¶
Package docparse parses the comments.
nolint
Index ¶
- func FindComments(w io.Writer, prog *Program) error
- func JSONSchemaType(t string) string
- func MapType(prog *Program, in string) (kind, format string)
- func ParseLookup(lookup string, filePath string) (name, pkg string)
- func PathParams(path string) []string
- type Config
- type DefaultResponse
- type EmptyInterface
- type EmptyStructInterfaces
- type Endpoint
- type ErrNotStruct
- type Param
- type Program
- type Ref
- type Reference
- type Request
- type Response
- type Schema
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindComments ¶
FindComments finds all comments in the given paths or packages.
func JSONSchemaType ¶
JSONSchemaType gets the type name as used in JSON schema.
func MapType ¶
MapType maps some Go types to primitives, so they appear as such in the output. Most of the time users of the API don't really care if it's a "sql.NullString" or just a string.
func ParseLookup ¶
ParseLookup for the package and name, if lookup is an imported path e.g models.Foo then: pkg: models, name: Foo in the case of current package the filePath is used, e.g: pkg: Dir(filePath), name: Foofunc ParseLookup(lookup string, filePath string) (name, pkg string) {
func PathParams ¶
PathParams returns all {..} delimited path parameters.
Types ¶
type Config ¶
type Config struct { // Kommentaar control. Packages []string Output func(io.Writer, *Program) error Debug bool // General information. Title string Description template.HTML Version string ContactName string ContactEmail string ContactSite string // Defaults. DefaultRequestCt string DefaultResponseCt string DefaultResponse map[int]Response Prefix string Basepath string StructTag string MapTypes map[string]string MapFormats map[string]string }
Config for the program.
type DefaultResponse ¶
type DefaultResponse struct { Lookup string // e.g. models.Foo Description string // e.g. "200 OK" Schema Schema }
DefaultResponse references.
type EmptyInterface ¶
type EmptyInterface interface{}
type EmptyStructInterfaces ¶
type EmptyStructInterfaces struct { Data interface{} DataArray []interface{} }
type Endpoint ¶
type Endpoint struct { Method string // HTTP method (e.g. POST, DELETE, etc.) Path string // Request path. Tags []string // Tags for grouping (optional). Tagline string // Single-line description (optional). Info string // More detailed description (optional). Request Request Responses map[int]Response Extend map[string]interface{} // Extension data to be applied on marshalling. Pos, End token.Position }
Endpoint denotes a single API endpoint.
type ErrNotStruct ¶
ErrNotStruct is used when GetReference resolves to something that is not a struct.
func (ErrNotStruct) Error ¶
func (err ErrNotStruct) Error() string
type Param ¶
type Param struct { Name string // Parameter name KindField *ast.Field // Type information from struct field. }
Param is a path, query, or form parameter.
type Ref ¶
type Ref struct { Description string // Main reason to store as a string (and Refs as a map) for now is so that // it looks pretties in the pretty.Print() output. May not want to keep // this. Reference string //*Reference }
Ref parameters for the path, query, form, request body, or response body.
type Reference ¶
type Reference struct { Name string // Name of the struct (without package name). Package string // Package in which the struct resides. File string // File this struct resides in. Lookup string // Identifier as pkg.type. Info string // Comment of the struct itself. Context string // Context we found it: path, query, form, req, resp. IsEmbed bool // Is an embedded struct. IsSlice bool // Is a slice Wrapper string // Name of json obj to wrap Schema in Schema *Schema // JSON schema. Fields []Param // Struct fields. }
Reference to a Go struct.
func GetReference ¶
func GetReference(prog *Program, context string, isEmbed bool, lookup, filePath string) (*Reference, error)
GetReference finds a type by name. It can either be in the current path ("SomeStruct"), a package path with a type (e.g. "example.com/bar.SomeStruct"), or something from an imported package (e.g. "models.SomeStruct").
References are stored in prog.References. This also finds and stores all nested references, so for:
type Foo struct { Field Bar }
A GetReference("Foo", "") call will add two entries to prog.References: Foo and Bar (but only Foo is returned).
type Request ¶
type Request struct { ContentType string // Content-Type that this request accepts for the body. Body *Ref // Request body; usually a JSON body. Path *Ref // Path parameters (e.g. /foo/{id}). Query *Ref // Query parameters (e.g. ?foo=id). Form *Ref // Form parameters. }
Request definition.
type Schema ¶
type Schema struct { Reference string `json:"$ref,omitempty" yaml:"$ref,omitempty"` Title string `json:"title,omitempty" yaml:"title,omitempty"` Description string `json:"description,omitempty" yaml:"description,omitempty"` Type string `json:"type,omitempty" yaml:"type,omitempty"` Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"` Format string `json:"format,omitempty" yaml:"format,omitempty"` Required []string `json:"required,omitempty" yaml:"required,omitempty"` Default string `json:"default,omitempty" yaml:"default,omitempty"` Minimum int `json:"minimum,omitempty" yaml:"minimum,omitempty"` Maximum int `json:"maximum,omitempty" yaml:"maximum,omitempty"` Readonly *bool `json:"readOnly,omitempty" yaml:"readOnly,omitempty"` FieldWhitelist []string `json:"field-whitelist,omitempty" yaml:"field-whitelist,omitempty"` // Store array items; for primitives: // "items": {"type": "string"} // or custom types: // "items": {"$ref": "#/definitions/positiveInteger"}, Items *Schema `json:"items,omitempty" yaml:"items,omitempty"` // Store structs. Properties map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"` // We will not forbid to add propreties to an struct, so instead of using the // bool value, we use the schema definition AdditionalProperties *Schema `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"` OmitDoc bool `json:"-" yaml:"-"` // {omitdoc} CustomSchema string `json:"-" yaml:"-"` // {schema: path} }
The Schema Object allows the definition of input and output data types.