Skip to content

documentation.mdx

Latest commit

 

History

History
270 lines (181 loc) · 8.14 KB

documentation.mdx

File metadata and controls

270 lines (181 loc) · 8.14 KB
Raw
title Documentation
description Documentation protocol schemas

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