docsData

package
v2.932.15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

README

Docs Data

The docsData package is responsible for creating a data structure that can be used to render docs. It does this by serializing the AST into a series of chunks, which are then sent to an external rendering process for conversion to docs pages. Docs are typically sent to the rendering process via JSONL files, but could also be sent over IPC or over a network connection.

Chunks

Core to this package is the concept of a “chunk.” A chunk is a piece of data that can be rendered into a piece of UI. Chunks are fairly similar to refs in OpenAPI, except that everything is represented as a chunk. Like refs, chunks can reference other chunks.

Some refs will correlate 1:1 with chunks, and vice versa, but this is not uniformly the case. Refs are optimized to help authors write specs more efficiently, i.e. they’re optimized for humans. Chunks however are optimized for later stages of rendering, i.e. they’re optimized for machines. As such, there are different needs of each.

Every chunk has the following base data structure:

{
  "id": "string",
  "slug": "string",
  "chunkType": "string",
  "chunkData": "object"
}
  • id - a unique id that represents this chunk. There is no semantic meaning to ids, other than that they are unique
  • slug - if non-empty, a unique URL friendly slug that represents this chunk. It may or may not be used as a URL in generated docs.
  • chunkType - a string identifying the chunk type. We use this during deserialization to know how to interpret the chunk
  • chunkData - the chunk specific data

Some examples of chunks:

  • about - a chunk that contains high-level information about the entire spec, and mostly comes from the info section of the spec
  • schema - a chunk that contains information about a schema, and is used to represent any piece of data used by operations, web hooks, etc.

Type definitions for each chunk are declared in the implementation file that processes each chunk.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetFormattedExamples 

func GetFormattedExamples(examples ast.Examples) []string

func GetSerializedDefault 

func GetSerializedDefault(field *ast.FieldDef) *string

func NewDocsData 

func NewDocsData(ast *ast.AST) ([]*string, error)

Creates docs data from the given AST. This function returns chunks in a serialized format that can be written to a JSONL file, sent across an IPC connection, sent over a network connection, etc.

func SerializeAbout 

func SerializeAbout(docs *Docs, ast *ast.AST) error

func SerializeOperation 

func SerializeOperation(docs *Docs, operation *ast.Operation, tag string) (string, error)

func SerializeSchema 

func SerializeSchema(docs *Docs, typeDef *ast.TypeDef, isNullable bool, defaultValue *string) (*string, error)

func SerializeSecurity 

func SerializeSecurity(docs *Docs, security *ast.TypeDef, isGlobal bool) (*string, error)

func SerializeTag 

func SerializeTag(docs *Docs, tag string, description *string, operationIds []string) error

Types

type AboutChunk 

type AboutChunk struct {
	ID        string    `json:"id"`
	Slug      string    `json:"slug"`
	ChunkData AboutData `json:"chunkData"`
	ChunkType string    `json:"chunkType"`
}

type AboutData 

type AboutData struct {
	Title          string   `json:"title"`
	Summary        string   `json:"summary"`
	Description    string   `json:"description"`
	TermsOfService string   `json:"termsOfService"`
	Version        string   `json:"version"`
	Contact        *Contact `json:"contact"`
	License        *License `json:"license"`
	Servers        []Server `json:"servers"`
}

type AnnotatedOperation 

type AnnotatedOperation struct {
	Operation *ast.Operation
	Tags      []string
}

type ArrayValue 

type ArrayValue struct {
	Type        ValueType   `json:"type"`
	Description *string     `json:"description"`
	Examples    []string    `json:"examples"`
	Items       SchemaValue `json:"items"`
	Default     *string     `json:"defaultValue"`
	MinItems    *int64      `json:"minItems"`
	MaxItems    *int64      `json:"maxItems"`
}

func NewArrayValue 

func NewArrayValue(arrayType ValueType, typeDef *ast.TypeDef, defaultValue *string) *ArrayValue

func (*ArrayValue) GetValueType 

func (a *ArrayValue) GetValueType() ValueType

func (*ArrayValue) ParseArrayTypeDef 

func (a *ArrayValue) ParseArrayTypeDef(docs *Docs, typeDef *ast.TypeDef) error

type ChunkValue 

type ChunkValue struct {
	Type    ValueType `json:"type"`
	ChunkId string    `json:"chunkId"`
}

func NewChunkValue 

func NewChunkValue(chunkId string) *ChunkValue

func (*ChunkValue) GetValueType 

func (c *ChunkValue) GetValueType() ValueType

type Contact 

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

Note: this is a trimmed down version of the Contact/License types found in the high-level model, since we don't want the low model or extensions

type Docs 

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

func (*Docs) GenerateID 

func (d *Docs) GenerateID() string

func (*Docs) GetCachedIdFromSlug 

func (d *Docs) GetCachedIdFromSlug(slug string) string

func (*Docs) RegisterSlug 

func (d *Docs) RegisterSlug(id string, slug string)

TODO: This is something of a quick-n-dirty way to record and check if we've processed an chunk before, to prevent infinite recursion. It's not great though since not all chunks have slugs. We'll need to fix a few issues to make this more robust though, so I'm punting for the time being.

func (*Docs) SaveSerializedChunk 

func (d *Docs) SaveSerializedChunk(id string, serializedChunk string)

Save a serialized chunk so that we can later save it to disk. One day, we can also use this to immediately send a chunk to the renderer over IPC/etc.

type EnumValue 

type EnumValue struct {
	Type        ValueType `json:"type"`
	Description *string   `json:"description"`
	Examples    []string  `json:"examples"`
	Values      []string  `json:"values"`
	Default     *string   `json:"defaultValue"`
}

func NewEnumValue 

func NewEnumValue(values []string, typeDef *ast.TypeDef, isNullable bool, defaultValue *string) *EnumValue

func (*EnumValue) GetValueType 

func (e *EnumValue) GetValueType() ValueType

type License 

type License struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

type ObjectValue 

type ObjectValue struct {
	Type        ValueType              `json:"type"`
	Description *string                `json:"description"`
	Examples    []string               `json:"examples"`
	Properties  map[string]SchemaValue `json:"properties"`
	Required    []string               `json:"required"`
	Deprecated  bool                   `json:"deprecated"`
	Name        string                 `json:"name"`
	Default     *string                `json:"defaultValue"`
}

func NewObjectValue 

func NewObjectValue(name string, typeDef *ast.TypeDef, defaultValue *string) *ObjectValue

func (*ObjectValue) GetValueType 

func (o *ObjectValue) GetValueType() ValueType

func (*ObjectValue) ParseObjectTypeDef 

func (o *ObjectValue) ParseObjectTypeDef(docs *Docs, typeDef *ast.TypeDef) error

type OperationChunk 

type OperationChunk struct {
	ID        string        `json:"id"`
	Slug      string        `json:"slug"`
	ChunkData OperationData `json:"chunkData"`
	ChunkType string        `json:"chunkType"`
}

type OperationData 

type OperationData struct {
	OperationID string                `json:"operationId"`
	Path        string                `json:"path"`
	Method      string                `json:"method"`
	Summary     string                `json:"summary"`
	Description string                `json:"description"`
	Parameters  []Parameter           `json:"parameters"`
	RequestBody *RequestBody          `json:"requestBody"`
	Responses   map[string][]Response `json:"responses"`
	Tag         string                `json:"tag"`
	Security    *Security             `json:"security"`
	Deprecated  bool                  `json:"deprecated"`
	CodeSamples map[string]string     `json:"codeSamples"`
}

type Parameter 

type Parameter struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	Required     bool   `json:"required"`
	Deprecated   bool   `json:"deprecated"`
	In           string `json:"in"`
	FieldChunkID string `json:"fieldChunkId"`
}

type PrimitiveValue 

type PrimitiveValue struct {
	Type        ValueType `json:"type"`
	Description *string   `json:"description"`
	Examples    []string  `json:"examples"`
	Default     *string   `json:"defaultValue"`
	MinLength   *int64    `json:"minLength"`
	MaxLength   *int64    `json:"maxLength"`
	Minimum     *float64  `json:"minimum"`
	Maximum     *float64  `json:"maximum"`
	Pattern     *string   `json:"pattern"`
}

func NewPrimitiveValue 

func NewPrimitiveValue(primitiveType ValueType, typeDef *ast.TypeDef, defaultValue *string) *PrimitiveValue

func (*PrimitiveValue) GetValueType 

func (p *PrimitiveValue) GetValueType() ValueType

type RequestBody 

type RequestBody struct {
	Description    string            `json:"description"`
	Required       bool              `json:"required"`
	ContentChunkID string            `json:"contentChunkId"`
	Examples       []TopLevelExample `json:"examples"`
}

type Response 

type Response struct {
	Description    string            `json:"description"`
	ContentType    string            `json:"contentType"`
	ContentChunkID string            `json:"contentChunkId"`
	Examples       []TopLevelExample `json:"examples"`
}

type SchemaChunk 

type SchemaChunk struct {
	ID        string     `json:"id"`
	Slug      string     `json:"slug"`
	ChunkData SchemaData `json:"chunkData"`
	ChunkType string     `json:"chunkType"`
}

type SchemaData 

type SchemaData struct {
	Name  string      `json:"name"`
	Value SchemaValue `json:"value"`
}

type SchemaValue 

type SchemaValue interface {
	GetValueType() ValueType
}

func ParseTypeDef 

func ParseTypeDef(docs *Docs, typeDef *ast.TypeDef, isNullable bool, defaultValue *string) (SchemaValue, error)

type Security 

type Security struct {
	ContentChunkID string `json:"contentChunkId"`
}

type SecurityChunk 

type SecurityChunk struct {
	ID        string       `json:"id"`
	Slug      string       `json:"slug"`
	ChunkData SecurityData `json:"chunkData"`
	ChunkType string       `json:"chunkType"`
}

type SecurityData 

type SecurityData struct {
	ID      string              `json:"id"`
	Entries []SecurityEntryData `json:"entries"`
}

type SecurityEntryData 

type SecurityEntryData struct {
	Type        string `json:"type"`
	Description string `json:"description"`
	Name        string `json:"name"`
	In          string `json:"in"`
}

type Server 

type Server struct {
	URL string `json:"url"`
}

type TagChunk 

type TagChunk struct {
	ID        string  `json:"id"`
	Slug      string  `json:"slug"`
	ChunkData TagData `json:"chunkData"`
	ChunkType string  `json:"chunkType"`
}

type TagData 

type TagData struct {
	Name              string   `json:"name"`
	Description       *string  `json:"description"`
	OperationChunkIds []string `json:"operationChunkIds"`
}

type TopLevelExample 

type TopLevelExample struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type UnionValue 

type UnionValue struct {
	Type        ValueType     `json:"type"`
	Description *string       `json:"description"`
	Examples    []string      `json:"examples"`
	Values      []SchemaValue `json:"values"`
	Default     *string       `json:"defaultValue"`
}

func NewNullableValue 

func NewNullableValue(valueType SchemaValue, typeDef *ast.TypeDef) *UnionValue

If a given type is nullable, we convert the type to a union type containing the given type and a null value

func NewUnionValue 

func NewUnionValue(typeDef *ast.TypeDef, defaultValue *string) *UnionValue

func (*UnionValue) GetValueType 

func (u *UnionValue) GetValueType() ValueType

func (*UnionValue) ParseUnionTypeDef 

func (u *UnionValue) ParseUnionTypeDef(docs *Docs, typeDef *ast.TypeDef) error

type ValueType 

type ValueType string
const (
	StringType         ValueType = "string"
	DateStringType     ValueType = "date"
	DateTimeStringType ValueType = "date-time"
	BooleanType        ValueType = "boolean"
	NumberType         ValueType = "number"
	IntegerType        ValueType = "integer"
	Int32Type          ValueType = "int32"
	Float32Type        ValueType = "float32"
	DecimalType        ValueType = "decimal"
	BigIntType         ValueType = "bigint"
	ObjectType         ValueType = "object"
	ArrayType          ValueType = "array"
	SetType            ValueType = "set"
	MapType            ValueType = "map"
	EventStreamType    ValueType = "event-stream"
	JsonLType          ValueType = "jsonl"
	UnionType          ValueType = "union"
	EnumType           ValueType = "enum"

	// We set null as a separate type and turn any type that is nullable into a
	// union of that type and a null type. This way, null shows up like any other
	// type in the UI
	NullType ValueType = "null"

	// DataTypeBytes, DataTypeRequestStream, DataTypeResponseStream are all
	// combined into this binary type here
	BinaryType ValueType = "binary"
	AnyType    ValueType = "any"

	// This type is used to create a layer of indirection such that objects and
	// arrays are never nested directly. This way we can serialize circular
	// references easily, and also more give the UI more flexibility when deciding
	// how to display deeply nested data. This type is the primary difference with
	// TypeDefs, since TypeDefs have no such concept.
	ChunkType ValueType = "chunk"
)

Most of these match the types in TypeDef 1:1, but there are a few differences

type XCodeSample 

type XCodeSample struct {
	Lang   string `json:"lang"`
	Label  string `json:"label"`
	Source string `json:"source"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.