Documentation
¶
Overview ¶
Package apidocs generates an OpenAPI 3.1 spec from the Hasura introspection result and any registered plugin REST routes. The output is written to .nself/dist/openapi.json and served by nginx at /api-docs. A self-contained Scalar HTML page is served at /docs.
Index ¶
- func NginxConf(docsServePath, baseDomain string) string
- type ApiDocsConfig
- type GenerateResult
- type OpenAPIComponents
- type OpenAPIInfo
- type OpenAPIMediaType
- type OpenAPIOperation
- type OpenAPIPathItem
- type OpenAPIRequestBody
- type OpenAPIResponse
- type OpenAPISchemaRef
- type OpenAPISecurityScheme
- type OpenAPIServer
- type OpenAPISpec
- type PluginRoute
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NginxConf ¶
NginxConf returns the nginx site configuration for /api-docs and /docs, served on docs.<baseDomain>. Output is a complete server { } block intended to live in nginx/sites/ alongside hasura.conf and auth.conf.
docsServePath is the path on the docs subdomain (default /docs); /api-docs is always served alongside it.
Types ¶
type ApiDocsConfig ¶
type ApiDocsConfig struct {
Enabled bool
Path string
Title string
Theme string // default | moon | purple | solarized
AuthEnvVar string // env var containing anon key for try-out pre-fill
HideEndpoints []string // path prefixes to exclude
GraphQLEnabled bool
GraphQLEndpoint string // default: /v1/graphql
}
ApiDocsConfig is the input type consumed by the apidocs package. The build orchestrator maps config.ApiDocsConfig → apidocs.ApiDocsConfig to avoid an import cycle (apidocs must not import config).
func DefaultApiDocsConfig ¶
func DefaultApiDocsConfig() ApiDocsConfig
DefaultApiDocsConfig returns defaults when api_docs is not configured.
type GenerateResult ¶
type GenerateResult struct {
// OpenAPIPath is the absolute path to the written openapi.json.
OpenAPIPath string
// ScalarHTMLPath is the absolute path to the written scalar.html.
ScalarHTMLPath string
}
GenerateResult is returned from Generate.
func Generate ¶
func Generate(workdir, projectName, baseDomain string, cfg ApiDocsConfig, pluginRoutes []PluginRoute) (*GenerateResult, error)
Generate builds the OpenAPI 3.1 spec and writes both dist files:
- .nself/dist/openapi.json
- .nself/dist/scalar.html
workdir is the nSelf project root (contains .nself/). projectName is used as the default API title. baseDomain is the primary domain (for the Servers list). cfg is the resolved ApiDocsConfig. pluginRoutes are REST routes contributed by plugins (from plugin_routes.go).
type OpenAPIComponents ¶
type OpenAPIComponents struct {
SecuritySchemes map[string]OpenAPISecurityScheme `json:"securitySchemes,omitempty"`
Schemas map[string]OpenAPISchemaRef `json:"schemas,omitempty"`
}
OpenAPIComponents holds reusable schemas and security schemes.
type OpenAPIInfo ¶
type OpenAPIInfo struct {
Title string `json:"title"`
Version string `json:"version"`
// x-nself-generated marks this as a generated spec.
Extensions map[string]interface{} `json:"-"`
}
OpenAPIInfo holds the API metadata.
type OpenAPIMediaType ¶
type OpenAPIMediaType struct {
Schema OpenAPISchemaRef `json:"schema"`
}
OpenAPIMediaType wraps a schema reference.
type OpenAPIOperation ¶
type OpenAPIOperation struct {
Summary string `json:"summary"`
OperationID string `json:"operationId"`
Tags []string `json:"tags,omitempty"`
RequestBody *OpenAPIRequestBody `json:"requestBody,omitempty"`
Responses map[string]OpenAPIResponse `json:"responses"`
Security []map[string][]string `json:"security,omitempty"`
// x-nself-websocket marks subscription operations.
XNselfWebsocket bool `json:"x-nself-websocket,omitempty"`
}
OpenAPIOperation is one HTTP operation.
type OpenAPIPathItem ¶
type OpenAPIPathItem map[string]*OpenAPIOperation
OpenAPIPathItem holds operations for a single path.
type OpenAPIRequestBody ¶
type OpenAPIRequestBody struct {
Required bool `json:"required"`
Content map[string]OpenAPIMediaType `json:"content"`
}
OpenAPIRequestBody describes the request payload.
type OpenAPIResponse ¶
type OpenAPIResponse struct {
Description string `json:"description"`
Content map[string]OpenAPIMediaType `json:"content,omitempty"`
}
OpenAPIResponse describes one response.
type OpenAPISchemaRef ¶
type OpenAPISchemaRef struct {
Ref string `json:"$ref,omitempty"`
Type string `json:"type,omitempty"`
Properties map[string]OpenAPISchemaRef `json:"properties,omitempty"`
Items *OpenAPISchemaRef `json:"items,omitempty"`
Nullable bool `json:"nullable,omitempty"`
}
OpenAPISchemaRef is a JSON Schema reference or inline schema.
type OpenAPISecurityScheme ¶
type OpenAPISecurityScheme struct {
Type string `json:"type"`
Scheme string `json:"scheme,omitempty"`
BearerFormat string `json:"bearerFormat,omitempty"`
Name string `json:"name,omitempty"`
In string `json:"in,omitempty"`
}
OpenAPISecurityScheme defines an auth method.
type OpenAPIServer ¶
OpenAPIServer lists base URLs.
type OpenAPISpec ¶
type OpenAPISpec struct {
OpenAPI string `json:"openapi"`
Info OpenAPIInfo `json:"info"`
Servers []OpenAPIServer `json:"servers"`
Paths map[string]OpenAPIPathItem `json:"paths"`
Components OpenAPIComponents `json:"components"`
}
OpenAPISpec is the top-level OpenAPI 3.1 document.
type PluginRoute ¶
type PluginRoute struct {
// PluginName is the plugin identifier (e.g. "ai", "notify").
PluginName string
// Method is the HTTP method (GET, POST, PUT, PATCH, DELETE).
Method string
// Path is the URL path (e.g. "/ai/v1/complete").
Path string
// Summary is a short human-readable description.
Summary string
}
PluginRoute is one REST route contributed by a plugin via its plugin.yaml rest_routes key.
func CollectPluginRoutes ¶
func CollectPluginRoutes(pluginDir string) ([]PluginRoute, error)
CollectPluginRoutes walks pluginDir and reads rest_routes from each plugin's manifest (plugin.yaml or plugin.json). Missing manifests are silently skipped.
Source Files