Skip to content

openapi-implementation.md

Latest commit

 

History

History
104 lines (85 loc) · 3.07 KB

openapi-implementation.md

File metadata and controls

104 lines (85 loc) · 3.07 KB

OpenAPI Documentation Implementation

Overview

We've successfully implemented OpenAPI documentation for the CodeQual API, providing comprehensive API reference documentation for developers.

What Was Implemented

1. OpenAPI Specification

  • Location: /apps/api/openapi.yaml
  • Format: OpenAPI 3.0.0
  • Coverage: All public v1 API endpoints
  • Features:
    • Complete schema definitions
    • Request/response examples
    • Authentication documentation
    • Error response formats
    • Rate limiting information

2. Documentation Routes

  • Endpoints:
    • /docs - HTML documentation page
    • /docs/openapi.json - JSON specification
    • /api/docs - Alternative path
  • File: /apps/api/src/routes/openapi-docs.ts

3. JSDoc Annotations

Added Swagger/JSDoc annotations to routes:

  • /apps/api/src/routes/analysis.ts
  • /apps/api/src/routes/result-orchestrator.ts
  • /apps/api/src/routes/api-keys.ts

4. Client SDK Generation

  • Script: /scripts/generate-api-clients.sh
  • Generates:
    • TypeScript/JavaScript SDK
    • Python SDK
    • Go SDK
    • Ruby SDK
    • Java SDK

5. Documentation & Examples

  • Getting Started Guide: /docs/api/getting-started.md
  • GitHub Actions Example: /docs/api/examples/github-actions.yml
  • Node.js Example: /docs/api/examples/node-example.ts

Key Features

Authentication

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
    description: API key for authentication

Endpoints Documented

  1. POST /v1/analyze-pr - Submit PR for analysis
  2. GET /v1/analysis/{id}/progress - Check analysis status
  3. GET /v1/analysis/history - Get analysis history
  4. GET /v1/reports/{id} - Get detailed reports
  5. GET /api/keys - List API keys (user auth)
  6. POST /api/keys - Create API key (user auth)
  7. DELETE /api/keys/{id} - Revoke API key (user auth)
  8. GET /api/keys/{id}/usage - Get usage stats (user auth)

Response Schemas

  • PRAnalysisRequest
  • AnalysisResponse
  • AnalysisProgress
  • AnalysisResults
  • Error responses
  • Rate limit information

Usage

For Developers

  1. Access documentation at: https://api.codequal.com/docs
  2. Get OpenAPI spec: https://api.codequal.com/docs/openapi.json
  3. Import into Postman/Insomnia for testing
  4. Generate client SDKs using the provided script

For Internal Development

  1. Documentation auto-updates from code annotations
  2. Run npm run generate-clients to update SDKs
  3. Test endpoints using the OpenAPI spec

Next Steps

  1. Add Swagger UI: When dependencies are properly installed
  2. Enhance Examples: Add more language-specific examples
  3. API Versioning: Implement version management
  4. Webhook Documentation: Add webhook event schemas
  5. GraphQL Alternative: Consider GraphQL API option

Benefits

  1. Developer Experience: Clear, interactive documentation
  2. SDK Generation: Automatic client library generation
  3. Type Safety: Strong typing for requests/responses
  4. Testing: Import spec into API testing tools
  5. Consistency: Single source of truth for API