@soulcraft/kits 1.0.0

package/src/kits/api-documentation.ts

@@ -0,0 +1,352 @@
+/**
+ * @module @soulcraft/kits/kits/api-documentation
+ * @description Complete API reference with endpoints, authentication, and examples
+ *
+ * Generated from: kits/api-documentation/kit.json
+ * Do not edit this file directly — edit the source kit.json and re-run `bun run build:kits`.
+ */
+
+import type { SoulcraftKitConfig } from '@soulcraft/kit-schema';
+
+/**
+ * API Documentation kit configuration.
+ *
+ * @description Complete API reference with endpoints, authentication, and examples
+ * @see {@link SoulcraftKitConfig}
+ */
+const apiDocumentation: SoulcraftKitConfig = {
+	"$schema": "https://soulcraft.com/schemas/kit/v2.json",
+	"id": "api-documentation",
+	"name": "API Documentation",
+	"description": "Complete API reference with endpoints, authentication, and examples",
+	"version": "1.0.0",
+	"author": {
+		"name": "Soulcraft Labs",
+		"email": "kits@soulcraft.com",
+		"url": "https://soulcraft.com"
+	},
+	"status": "released",
+	"icon": "⚡",
+	"longDescription": "Professional API documentation structure with endpoint specifications, authentication guides, code examples, and error handling. Includes OpenAPI/Swagger export capabilities.",
+	"tags": [
+		"api",
+		"documentation",
+		"development",
+		"technical"
+	],
+	"role": "primary",
+	"type": "soulcraft",
+	"variables": [
+		{
+			"key": "projectName",
+			"label": "API Name",
+			"description": "The name of the API being documented",
+			"type": "string",
+			"required": true,
+			"example": "Payment Processing API"
+		},
+		{
+			"key": "version",
+			"label": "Version",
+			"description": "API version number",
+			"type": "string",
+			"required": false,
+			"example": "v1.0"
+		},
+		{
+			"key": "baseUrl",
+			"label": "Base URL",
+			"description": "The root URL for all API endpoints",
+			"type": "string",
+			"required": false,
+			"example": "https://api.example.com"
+		}
+	],
+	"shared": {
+		"industry": "software-development",
+		"category": "dev",
+		"glossary": {},
+		"aiExpertise": [
+			"API documentation best practices",
+			"OpenAPI/Swagger specification",
+			"REST endpoint design",
+			"Authentication flows",
+			"Developer experience"
+		],
+		"dataModelHints": [
+			"document",
+			"thing",
+			"topic"
+		],
+		"suggestions": [
+			{
+				"label": "Add an endpoint",
+				"prompt": "Help me document a new API endpoint"
+			},
+			{
+				"label": "Generate examples",
+				"prompt": "Generate request and response examples for my API endpoints"
+			},
+			{
+				"label": "Write authentication docs",
+				"prompt": "Help me write the authentication section of my API documentation"
+			},
+			{
+				"label": "Create error reference",
+				"prompt": "Help me create a comprehensive error code reference"
+			},
+			{
+				"label": "Review consistency",
+				"prompt": "Review my API documentation for consistency in naming and formatting"
+			},
+			{
+				"label": "Explore API structure",
+				"prompt": "Show me the structure of my API documentation and what's complete"
+			}
+		],
+		"dataModel": {
+			"entities": [
+				{
+					"domain": "endpoint",
+					"type": "Concept",
+					"description": "An API endpoint with HTTP method, path, and contract",
+					"products": {
+						"workshop": {
+							"view": "tree",
+							"icon": "⚡"
+						},
+						"academy": {
+							"mapsTo": "knowledge-unit",
+							"assessable": true
+						}
+					}
+				},
+				{
+					"domain": "resource",
+					"type": "Concept",
+					"description": "A domain object or data resource operated on by endpoints",
+					"products": {
+						"workshop": {
+							"view": "graph",
+							"icon": "🗂️"
+						},
+						"academy": {
+							"mapsTo": "knowledge-unit",
+							"assessable": true
+						}
+					}
+				},
+				{
+					"domain": "errorCode",
+					"type": "Concept",
+					"description": "An error code with meaning, cause, and resolution",
+					"products": {
+						"workshop": {
+							"view": "gallery",
+							"icon": "⚠️"
+						},
+						"academy": {
+							"mapsTo": "knowledge-unit",
+							"assessable": true
+						}
+					}
+				},
+				{
+					"domain": "parameter",
+					"type": "Concept",
+					"description": "A request or response field with type and constraints",
+					"products": {
+						"workshop": {
+							"view": "tree",
+							"icon": "🔧"
+						},
+						"academy": {
+							"mapsTo": "knowledge-unit",
+							"assessable": true
+						}
+					}
+				}
+			],
+			"relationships": [
+				{
+					"from": "endpoint",
+					"to": "resource",
+					"verb": "References",
+					"description": "Endpoint operates on this resource"
+				},
+				{
+					"from": "endpoint",
+					"to": "errorCode",
+					"verb": "Returns",
+					"description": "Endpoint can return this error code"
+				},
+				{
+					"from": "resource",
+					"to": "parameter",
+					"verb": "Contains",
+					"description": "Resource has this field or parameter"
+				},
+				{
+					"from": "endpoint",
+					"to": "endpoint",
+					"verb": "RelatedTo",
+					"description": "Related endpoints within the same resource group"
+				}
+			]
+		}
+	},
+	"workshop": {
+		"workspaceConfig": {
+			"paradigm": "analyst",
+			"defaultTab": "edit",
+			"defaultView": "tree",
+			"defaultFile": "README.md"
+		},
+		"graphGuidance": {
+			"conceptCreation": {
+				"triggers": [
+					"When user creates an endpoint",
+					"When user defines a resource",
+					"When user specifies an error code",
+					"When user documents authentication"
+				],
+				"typeMapping": {
+					"endpoint": "interface",
+					"resource": "concept",
+					"errorCode": "concept",
+					"parameter": "concept"
+				}
+			},
+			"relationshipPatterns": [
+				{
+					"from": "interface",
+					"to": "concept",
+					"verb": "references",
+					"description": "Endpoint uses resource"
+				},
+				{
+					"from": "interface",
+					"to": "concept",
+					"verb": "returns",
+					"description": "Endpoint returns error"
+				},
+				{
+					"from": "concept",
+					"to": "concept",
+					"verb": "contains",
+					"description": "Resource contains field"
+				},
+				{
+					"from": "interface",
+					"to": "interface",
+					"verb": "relatedTo",
+					"description": "Related endpoints"
+				}
+			],
+			"rules": [
+				"Create interface entities for endpoints",
+				"Document resources and their fields",
+				"Track error codes per endpoint",
+				"Note authentication requirements"
+			]
+		},
+		"qualityGates": {
+			"fileChecks": [
+				{
+					"path": "README.md",
+					"required": [
+						"Base URL",
+						"Authentication",
+						"Quick Start"
+					],
+					"optional": [
+						"SDK",
+						"Rate Limits"
+					]
+				},
+				{
+					"path": "authentication.md",
+					"required": [
+						"Authorization",
+						"API Key"
+					],
+					"optional": [
+						"OAuth",
+						"Scopes",
+						"Security"
+					]
+				},
+				{
+					"path": "errors.md",
+					"required": [
+						"Error Response Format",
+						"Status Codes"
+					],
+					"optional": [
+						"Error Codes",
+						"Troubleshooting"
+					]
+				}
+			],
+			"projectChecks": [
+				"At least one resource with CRUD endpoints documented",
+				"Authentication section is complete with examples",
+				"Error handling documentation exists",
+				"All endpoints have request/response examples",
+				"Rate limiting is documented"
+			],
+			"exportReady": [
+				"All endpoints have complete documentation",
+				"Code examples exist for primary language(s)",
+				"Authentication flows are fully documented",
+				"All status codes and errors are documented",
+				"Examples use consistent, realistic data"
+			]
+		},
+		"aiPersona": {
+			"role": "You are an expert API documentation specialist helping developers create clear, complete, and consistent reference documentation.",
+			"expertise": [
+				"API documentation best practices",
+				"OpenAPI/Swagger specification",
+				"Endpoint design and naming",
+				"Authentication documentation",
+				"Error handling documentation"
+			],
+			"tone": "mentor"
+		},
+		"exporters": [
+			{
+				"id": "markdown-docs",
+				"name": "Documentation Bundle",
+				"description": "Complete API documentation as ZIP",
+				"icon": "📚",
+				"format": "zip",
+				"category": "document",
+				"handler": "markdown-bundle"
+			}
+		],
+		"difficulty": "intermediate",
+		"templateTier": 4,
+		"templateMetadata": {
+			"identifyByStructure": true
+		}
+	},
+	"academy": {
+		"skillPath": "technical-writing",
+		"level": "intermediate",
+		"learningObjectives": [
+			"Write endpoint specifications that developers can implement without asking follow-up questions",
+			"Structure authentication documentation covering all supported flows with code examples",
+			"Design an error taxonomy with machine-readable codes and actionable resolution guidance",
+			"Apply OpenAPI/Swagger conventions to produce spec-compliant reference documentation",
+			"Review and edit API docs for consistency in naming, tone, and formatting"
+		],
+		"assessmentTypes": [
+			"portfolio",
+			"peer-review"
+		],
+		"certificationSlug": "api-documenter"
+	}
+} satisfies SoulcraftKitConfig;
+
+export default apiDocumentation;