kommentaarzgo.at/kommentaar/docparse Index | Files

package docparse

import "zgo.at/kommentaar/docparse"

Package docparse parses the comments.




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 PathParams

func PathParams(path string) []string

PathParams returns all {..} delimited path parameters.


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
	Auth         string

	// Defaults.
	DefaultRequestCt   string
	DefaultResponseCt  string
	DefaultResponse    map[int]Response
	AddDefaultResponse []int
	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 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
	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.
	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"`
	Title       string   `json:"title,omitempty"`
	Description string   `json:"description,omitempty"`
	Type        string   `json:"type,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Format      string   `json:"format,omitempty"`
	Required    []string `json:"required,omitempty"`
	Default     string   `json:"default,omitempty"`
	Minimum     int      `json:"minimum,omitempty"`
	Maximum     int      `json:"maximum,omitempty"`
	Readonly    *bool    `json:"readOnly,omitempty"`

	// Store array items; for primitives:
	//   "items": {"type": "string"}
	// or custom types:
	//   "items": {"$ref": "#/definitions/positiveInteger"},
	Items *Schema `json:"items,omitempty"`

	// Store structs.
	Properties map[string]*Schema `json:"properties,omitempty"`

	// Order of the properties in the struct; contains the key of the Properties
	// field.
	PropertyOrder []string `json:"-"`

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

	OmitDoc bool `json:"-"` // {omitdoc}

The Schema Object allows the definition of input and output data types.

Source Files

docparse.go find.go jsonschema.go test.go

v0.0.0-20230517222226-0b90222c1cce (latest)
May 17, 2023
20 packages
Last checked
1 month ago

Tools for package owners.