api-docs.template

Codex Runtime Compatibility

This prompt was authored for Claude-style slash workflows. In Codex runtime, adapt tool calls as follows:

• AskUserQuestion => ask the user directly in chat.
• WebSearch/WebFetch => use available web tools (search_query, open, find) and cite links.
• Read/Write => use shell/filesystem tools in this workspace.
• Claude-only MCP calls (for example Playwright MCP names) => use available equivalents or clearly state fallback.
• Keep intent and output format identical; only adapt execution mechanics.

---

description: Generate comprehensive API documentation type: project complexity: medium allowed-tools: Bash, Read, Write, Grep, Glob category: documentation

/api-docs

Auto-generate OpenAPI/Swagger documentation for your API.

Usage

/api-docs
/api-docs --generate
/api-docs --serve
/api-docs --postman

What It Does

1. Detect API Framework - Identify Express, FastAPI, etc.
2. Generate OpenAPI Spec - Create OpenAPI 3.0 specification
3. Add Documentation - Document all endpoints
4. Request/Response Examples - Add example payloads
5. Generate Postman Collection - Export for testing
6. Host Documentation - Set up Swagger UI or Redoc

---

Step 1: Detect API Framework

{{#if backend.framework}}

Detected Backend: {{backend.framework}}

{{#if (eq backend.framework "express")}} Strategy: Install swagger-jsdoc + swagger-ui-express {{/if}}

{{#if (eq backend.framework "fastapi")}} Strategy: Use built-in OpenAPI generator {{/if}}

{{#if (eq backend.framework "nest")}} Strategy: Use @nestjs/swagger {{/if}}

{{else}}

No backend framework detected. Will analyze routes manually.

{{/if}}

---

Step 2: Installation & Setup

Express.js

npm install swagger-jsdoc swagger-ui-express
npm install --save-dev @types/swagger-jsdoc @types/swagger-ui-express

Create src/swagger.js:

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '{{projectName}} API',
      version: '1.0.0',
      description: 'API documentation for {{projectName}}',
      contact: {
        name: 'API Support',
        email: '[email protected]',
      },
    },
    servers: [
      {
        url: '{{deployment.backend.productionUrl}}',
        description: 'Production server',
      },
      {
        url: 'http://localhost:{{backend.devServerPort || 8001}}',
        description: 'Development server',
      },
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        },
      },
    },
    security: [
      {
        bearerAuth: [],
      },
    ],
  },
  apis: ['./src/routes/*.js', './src/routes/*.ts'], // Path to route files
};

const specs = swaggerJsdoc(options);

module.exports = { specs, swaggerUi };