Documentation

API Documentation & Testing Interface Protocol

Provides schemas for generating interactive API documentation and testing

interfaces similar to Swagger UI, GraphQL Playground, Postman, etc.

Features:

OpenAPI/Swagger specification generation
Interactive API testing playground
API versioning and changelog
Code generation templates
Mock server configuration

Architecture Alignment:

Swagger UI: Interactive API documentation
Postman: API testing collections
GraphQL Playground: GraphQL-specific testing
Redoc: Documentation rendering

@example Documentation Config


const docConfig: ApiDocumentationConfig = \{

enabled: true,

title: 'ObjectStack API',

version: '1.0.0',

servers: [\{ url: 'https://api.example.com', description: 'Production' \}],

ui: \{

type: 'swagger-ui',

theme: 'light',

enableTryItOut: true

\}

\}

Source: packages/spec/src/api/documentation.zod.ts

TypeScript Usage

import { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api';
import type { ApiChangelogEntry, ApiDocumentationConfig, ApiTestCollection, ApiTestRequest, ApiTestingUiConfig, ApiTestingUiType, CodeGenerationTemplate, GeneratedApiDocumentation, OpenApiSecurityScheme, OpenApiServer, OpenApiSpec } from '@objectstack/spec/api';

// Validate data
const result = ApiChangelogEntry.parse(data);

ApiChangelogEntry

Properties

Property	Type	Required	Description
version	`string`	✅	API version
date	`string`	✅	Release date
changes	`Object`	✅	Version changes
migrationGuide	`string`	optional	Migration guide URL or text

ApiDocumentationConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable API documentation
title	`string`	✅	Documentation title
version	`string`	✅	API version
description	`string`	optional	API description
servers	`Object[]`	✅	API server URLs
ui	`Object`	optional	Testing UI configuration
generateOpenApi	`boolean`	✅	Generate OpenAPI 3.0 specification
generateTestCollections	`boolean`	✅	Generate API test collections
testCollections	`Object[]`	✅	Predefined test collections
changelog	`Object[]`	✅	API version changelog
codeTemplates	`Object[]`	✅	Code generation templates
termsOfService	`string`	optional	Terms of service URL
contact	`Object`	optional	Contact information
license	`Object`	optional	API license
externalDocs	`Object`	optional	External documentation link
securitySchemes	`Record<string, Object>`	optional	Security scheme definitions
tags	`Object[]`	optional	Global tag definitions

ApiTestCollection

Properties

Property	Type	Required	Description
name	`string`	✅	Collection name
description	`string`	optional	Collection description
variables	`Record<string, any>`	✅	Shared variables
requests	`Object[]`	✅	Test requests in this collection
folders	`Object[]`	optional	Request folders for organization

ApiTestRequest

Properties

Property	Type	Required	Description
name	`string`	✅	Test request name
description	`string`	optional	Request description
method	`Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>`	✅	HTTP method
url	`string`	✅	Request URL (can include variables)
headers	`Record<string, string>`	✅	Request headers
queryParams	`Record<string, string \| number \| boolean>`	✅	Query parameters
body	`any`	optional	Request body
variables	`Record<string, any>`	✅	Template variables
expectedResponse	`Object`	optional	Expected response for validation

ApiTestingUiConfig

Properties

Property	Type	Required	Description
type	`Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphql-playground' \| 'graphiql' \| 'postman' \| 'custom'>`	✅	Testing UI implementation
path	`string`	✅	URL path for documentation UI
theme	`Enum<'light' \| 'dark' \| 'auto'>`	✅	UI color theme
enableTryItOut	`boolean`	✅	Enable interactive API testing
enableFilter	`boolean`	✅	Enable endpoint filtering
enableCors	`boolean`	✅	Enable CORS for browser testing
defaultModelsExpandDepth	`integer`	✅	Default expand depth for schemas (-1 = fully expand)
displayRequestDuration	`boolean`	✅	Show request duration
syntaxHighlighting	`boolean`	✅	Enable syntax highlighting
customCssUrl	`string`	optional	Custom CSS stylesheet URL
customJsUrl	`string`	optional	Custom JavaScript URL
layout	`Object`	optional	Layout configuration

ApiTestingUiType

Allowed Values

swagger-ui
redoc
rapidoc
stoplight
scalar
graphql-playground
graphiql
postman
custom

CodeGenerationTemplate

Properties

Property	Type	Required	Description
language	`string`	✅	Target language/framework (e.g., typescript, python, curl)
name	`string`	✅	Template name
template	`string`	✅	Code template with placeholders
variables	`string[]`	optional	Required template variables

GeneratedApiDocumentation

Properties

Property	Type	Required	Description
openApiSpec	`Object`	optional	Generated OpenAPI specification
testCollections	`Object[]`	optional	Generated test collections
markdown	`string`	optional	Generated markdown documentation
html	`string`	optional	Generated HTML documentation
generatedAt	`string`	✅	Generation timestamp
sourceApis	`string[]`	✅	Source API IDs used for generation

OpenApiSecurityScheme

Properties

Property	Type	Required	Description
type	`Enum<'apiKey' \| 'http' \| 'oauth2' \| 'openIdConnect'>`	✅	Security type
scheme	`string`	optional	HTTP auth scheme (bearer, basic, etc.)
bearerFormat	`string`	optional	Bearer token format (e.g., JWT)
name	`string`	optional	API key parameter name
in	`Enum<'header' \| 'query' \| 'cookie'>`	optional	API key location
flows	`Object`	optional	OAuth2 flows
openIdConnectUrl	`string`	optional	OpenID Connect discovery URL
description	`string`	optional	Security scheme description

OpenApiServer

Properties

Property	Type	Required	Description
url	`string`	✅	Server base URL
description	`string`	optional	Server description
variables	`Record<string, Object>`	optional	URL template variables

OpenApiSpec

Properties

Property	Type	Required	Description
openapi	`string`	✅	OpenAPI specification version
info	`Object`	✅	API metadata
servers	`Object[]`	✅	API servers
paths	`Record<string, any>`	✅	API paths and operations
components	`Object`	optional	Reusable components
security	`Record<string, string[]>[]`	optional	Global security requirements
tags	`Object[]`	optional	Tag definitions
externalDocs	`Object`	optional	External documentation

On this page