---
title: Documentation
description: Documentation protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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

```typescript

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

\}

\}

```

<Callout type="info">
**Source:** `packages/spec/src/api/documentation.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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 |


---

