docparse

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
  • func (err ErrNotStruct) Error() string
• type Param
• type Program
  • func NewProgram(dbg bool) *Program
• type Ref
• type Reference
  • func GetReference(prog *Program, context string, isEmbed bool, lookup, filePath string) (*Reference, error)
• type Request
• type Response
  • func ParseResponse(prog *Program, filePath, line string) (int, *Response, error)
• type Schema

Functions

func FindComments

func FindComments(w io.Writer, prog *Program) error

FindComments finds all comments in the given paths or packages.

func JSONSchemaType

func JSONSchemaType(t string) string

JSONSchemaType gets the type name as used in JSON schema.

func MapType

func MapType(prog *Program, in string) (kind, format string)

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

func ParseLookup(lookup string, filePath string) (name, pkg string)

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

func PathParams(path string) []string

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

type ErrNotStruct struct {
	TypeSpec *ast.TypeSpec
	// contains filtered or unexported fields
}

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 Program

type Program struct {
	Config     Config
	Endpoints  []*Endpoint
	References map[string]Reference
}

Program is the entire program: all collected endpoints and all collected references.

func NewProgram

func NewProgram(dbg bool) *Program

NewProgram creates a new Program instance.

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 Response

type Response struct {
	ContentType string // Content-Type.
	Body        *Ref   // Body.
}

Response definition.

func ParseResponse

func ParseResponse(prog *Program, filePath, line string) (int, *Response, error)

ParseResponse parses a Response line.

Exported so it can be used in the config, too.

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.