Documentation
¶
Index ¶
- Constants
- Variables
- func CountNodes(nodes []ParamNode) int
- func IsValidAPIType(t string) bool
- func IsValidMethod(m string) bool
- func IsValidParamType(t string) bool
- func IsValidParamValueType(t string) bool
- func SetTablePrefix(p string)
- type API
- type Group
- type ImportAPI
- type ImportFormat
- type ImportGroup
- type ImportPlan
- type ImportResult
- type KnotExportAPI
- type KnotExportDocument
- type KnotExportGroup
- type KnotExportParams
- type ParamNode
- type Parameter
Constants ¶
const WireFormat = "knot"
WireFormat is the format identifier written into every Knot JSON export document ("knot"). Consumers use it to recognize Knot files; the export builder and the format detector must agree on this value.
const WireVersion = 1
WireVersion is the version of the Knot JSON export envelope currently produced and accepted for import.
Variables ¶
var APITypes = []string{"HTTP", "RPC"}
APITypes lists the supported API types.
var HTTPMethods = []string{"GET", "POST", "PUT", "DELETE", "PATCH"}
HTTPMethods lists the HTTP methods an API endpoint may declare.
var ParamTypes = []string{"request", "response"}
ParamTypes lists the parameter categories (request or response body).
var ParamValueTypes = []string{"string", "number", "boolean", "array", "object"}
ParamValueTypes lists the allowed parameter value types.
var TablePrefix string
TablePrefix is prepended to every model table name (see Group.TableName, API.TableName and Parameter.TableName). The default empty string keeps the v1.0 physical schema unchanged: groups, apis, parameters.
TablePrefix is process-global state. Embedders that share one database with other software set it (e.g. "knot_") so Knot's tables are namespaced; everything else leaves it empty. Use SetTablePrefix to assign it — never write the variable from multiple goroutines.
Functions ¶
func CountNodes ¶
CountNodes returns the total number of nodes in a ParamNode tree, including all descendants. Used for ImportResult.ParametersImported.
func IsValidAPIType ¶
IsValidAPIType reports whether t is one of the supported API types. Membership is case-sensitive.
func IsValidMethod ¶
IsValidMethod reports whether m is one of the supported HTTP methods. Membership is case-sensitive.
func IsValidParamType ¶
IsValidParamType reports whether t is a valid parameter category. Membership is case-sensitive.
func IsValidParamValueType ¶
IsValidParamValueType reports whether t is a valid parameter value type. Membership is case-sensitive.
func SetTablePrefix ¶ added in v1.1.0
func SetTablePrefix(p string)
SetTablePrefix sets the process-wide prefix for all model table names.
Contract: call it exactly once, before the first database use (before opening a connection or running any migration/query), and run a single engine instance per process. GORM resolves each model's table name when its schema is first parsed and caches the result per *gorm.DB, so a running database never observes later prefix changes — changing the prefix after tables exist will not rename them and will strand existing data under the old names.
Types ¶
type API ¶
type API struct {
ID uint `gorm:"primaryKey;autoIncrement" json:"id"`
GroupID uint `gorm:"not null;index:idx_group_id" json:"groupId"`
Group *Group `gorm:"foreignKey:GroupID" json:"group,omitempty"`
Name string `gorm:"not null" json:"name"`
Endpoint string `gorm:"not null" json:"endpoint"`
Method string `gorm:"type:varchar(10)" json:"method"` // GET, POST, PUT, DELETE, PATCH
Type string `gorm:"not null" json:"type"` // HTTP or RPC
Order int `gorm:"default:0" json:"order"`
Note *string `gorm:"type:text" json:"note"`
Parameters []Parameter `gorm:"foreignKey:APIID;constraint:OnDelete:CASCADE" json:"parameters,omitempty"`
CreatedAt int64 `gorm:"autoCreateTime" json:"-"`
UpdatedAt int64 `gorm:"autoUpdateTime" json:"-"`
}
API represents an API endpoint
func (API) MarshalJSON ¶
MarshalJSON customizes JSON serialization to convert timestamps to ISO 8601 strings
type Group ¶
type Group struct {
ID uint `gorm:"primaryKey;autoIncrement" json:"id"`
Name string `gorm:"unique;not null" json:"name"`
Order int `gorm:"default:0" json:"order"`
APIs []API `gorm:"foreignKey:GroupID;constraint:OnDelete:CASCADE" json:"apis,omitempty"`
CreatedAt int64 `gorm:"autoCreateTime" json:"-"`
UpdatedAt int64 `gorm:"autoUpdateTime" json:"-"`
}
Group represents an API group/collection
func (Group) MarshalJSON ¶
MarshalJSON customizes JSON serialization to convert timestamps to ISO 8601 strings
type ImportAPI ¶
type ImportAPI struct {
Name string
Endpoint string
Method string
Type string
Note *string
Request []ParamNode
Response []ParamNode
}
ImportAPI is one API entry within an import plan group. Note is a pointer so a missing note stays distinguishable from an empty one.
type ImportFormat ¶
type ImportFormat string
ImportFormat identifies the exchange format of an uploaded import file. The string values are stable identifiers used by the import handler.
const ( ImportFormatKnot ImportFormat = "knot-json" ImportFormatPostman ImportFormat = "postman" ImportFormatOpenAPI ImportFormat = "openapi" )
type ImportGroup ¶
ImportGroup is one API group within an import plan.
type ImportPlan ¶
type ImportPlan struct {
Groups []ImportGroup
Warnings []string
}
ImportPlan is the shared intermediate representation that every importer (Knot JSON, Postman, OpenAPI) produces from an uploaded file. The import apply step consumes it; Warnings collects non-fatal issues encountered while parsing so they can be surfaced to the user after import.
type ImportResult ¶ added in v1.1.0
type ImportResult struct {
Format string `json:"format"`
GroupsCreated int `json:"groupsCreated"`
GroupsMerged int `json:"groupsMerged"`
APIsImported int `json:"apisImported"`
ParametersImported int `json:"parametersImported"`
Warnings []string `json:"warnings"`
}
ImportResult reports what an applied import plan did (or, for a dry run, what it would do). It is the payload of the import preview/confirm flow.
type KnotExportAPI ¶
type KnotExportAPI struct {
Name string `json:"name"`
Endpoint string `json:"endpoint"`
Method string `json:"method"`
Type string `json:"type"`
Order int `json:"order"`
Note *string `json:"note"`
Parameters KnotExportParams `json:"parameters"`
}
KnotExportAPI is one API entry within a group.
type KnotExportDocument ¶
type KnotExportDocument struct {
Format string `json:"format"`
Version int `json:"version"`
ExportedAt string `json:"exportedAt"`
Groups []KnotExportGroup `json:"groups"`
}
KnotExportDocument is the top-level structure of a Knot JSON v1 export file.
type KnotExportGroup ¶
type KnotExportGroup struct {
Name string `json:"name"`
Order int `json:"order"`
APIs []KnotExportAPI `json:"apis"`
}
KnotExportGroup is one API group within a Knot export document.
type KnotExportParams ¶
type KnotExportParams struct {
Request []ParamNode `json:"request"`
Response []ParamNode `json:"response"`
}
KnotExportParams holds the request and response parameter trees of one API.
type ParamNode ¶
type ParamNode struct {
Name string `json:"name"`
Type string `json:"type"` // string|number|boolean|array|object
Required bool `json:"required"`
Description *string `json:"description"`
Order int `json:"order"`
Children []ParamNode `json:"children"`
}
ParamNode is a portable representation of a parameter tree node used by multi-format export/import. It mirrors Parameter without persistence or ORM concerns so it can be serialized to any exchange format.
func ParamNodesFromJSONValue ¶
func ParamNodesFromJSONValue(v interface{}) []ParamNode
ParamNodesFromJSONValue converts a decoded JSON value (as produced by json.Unmarshal into interface{}) into ParamNodes on a best-effort basis: string→string, float64→number, bool→boolean, []interface{}→array, map[string]interface{}→object. Map keys are sorted for deterministic order. A non-object top-level value yields no nodes. Used by the Postman importer for raw JSON bodies.
func TreeFromParams ¶
TreeFromParams converts flat ordered parameter rows (as fetched for one API and paramType) into a nested tree of ParamNode. Input row order is preserved for both roots and siblings. Rows whose ParentID references an unknown parameter are dropped, mirroring BuildParameterTree.
type Parameter ¶
type Parameter struct {
ID uint `gorm:"primaryKey;autoIncrement" json:"id"`
APIID uint `gorm:"not null;index:idx_api_param" json:"apiId"`
API *API `gorm:"foreignKey:APIID" json:"-"`
ParentID *uint `gorm:"index:idx_parent" json:"parentId"`
Parent *Parameter `gorm:"foreignKey:ParentID" json:"-"`
Children []Parameter `gorm:"foreignKey:ParentID" json:"children,omitempty"`
Name string `gorm:"not null" json:"name"`
Type string `gorm:"not null" json:"type"` // string, number, boolean, array, object
Description *string `gorm:"type:text" json:"description"`
Required bool `gorm:"default:false" json:"required"`
ParamType string `gorm:"not null;index:idx_api_param" json:"paramType"` // request or response
Order int `gorm:"not null;index:idx_api_param" json:"order"`
CreatedAt int64 `gorm:"autoCreateTime" json:"-"`
UpdatedAt int64 `gorm:"autoUpdateTime" json:"-"`
}
Parameter represents request/response parameters with support for nested structures
func (Parameter) MarshalJSON ¶
MarshalJSON customizes JSON serialization to convert timestamps to ISO 8601 strings