openapi: 3.0.0
info:
  title: CVS Proxy REST API
  description: A Flask-based REST API that provides a proxy for CVS (Concurrent Versions System) repository operations. It allows programmatic access to repository information and file contents.
  version: 1.0.0
  contact:
    name: CVS Proxy Support
  license:
    name: MIT

servers:
  - url: http://localhost:5000
    description: Local development server
  - url: https://api.example.com
    description: Production server (configure as needed)

tags:
  - name: Repository
    description: Operations for accessing repository structure and content
  - name: Health
    description: Service health and status checks

paths:
  /v1/tree:
    get:
      summary: List repository tree structure
      description: Retrieves the directory tree structure of the CVS repository, optionally filtered by module
      operationId: getRepositoryTree
      tags:
        - Repository
      parameters:
        - name: module
          in: query
          description: Optional module or subdirectory to list. If not provided, lists the entire repository
          required: false
          schema:
            type: string
          example: project_name
      responses:
        '200':
          description: Successfully retrieved repository tree
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: File or directory path
                example:
                  - src/main.py
                  - src/utils.py
                  - README.md
                  - config/settings.json
        '500':
          description: CVS Client not initialized or error retrieving tree
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: CVS Client not initialized

  /v1/diff:
    get:
      summary: Get diff between two revisions of a file
      description: Retrieves the unified diff output between two specified revisions of a file
      operationId: getFileDiff
      tags:
        - Repository
      parameters:
        - name: file
          in: query
          description: Path to the file in the repository
          required: true
          schema:
            type: string
          example: src/main.py
        - name: rev1
          in: query
          description: First revision number (e.g., 1.1, 1.2)
          required: true
          schema:
            type: string
          example: "1.1"
        - name: rev2
          in: query
          description: Second revision number (e.g., 1.2, 1.3)
          required: true
          schema:
            type: string
          example: "1.2"
      responses:
        '200':
          description: Successfully retrieved diff between revisions
          content:
            application/json:
              schema:
                type: object
                properties:
                  diff:
                    type: string
                    description: Unified diff output
                example:
                  diff: |
                    --- src/main.py	1.1
                    +++ src/main.py	1.2
                    @@ -1,5 +1,6 @@
                     def main():
                    -    print("Hello")
                    +    print("Hello World")
                         return 0
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing required parameters
        '500':
          description: CVS Client not initialized or error generating diff
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Error generating diff for src/main.py between 1.1 and 1.2

  /v1/history:
    get:
      summary: Get revision history for a file
      description: Retrieves the complete revision history including dates, authors, and change information for a specified file
      operationId: getFileHistory
      tags:
        - Repository
      parameters:
        - name: file
          in: query
          description: Path to the file in the repository
          required: true
          schema:
            type: string
          example: README.md
      responses:
        '200':
          description: Successfully retrieved file revision history
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    revision:
                      type: string
                      description: Revision number
                      example: "1.3"
                    date:
                      type: string
                      description: Date and time of the revision
                      example: "2024-01-15 10:30:45"
                    author:
                      type: string
                      description: Author who made the revision
                      example: john_doe
                    state:
                      type: string
                      description: State of the revision (e.g., Exp, dead)
                      example: Exp
                    lines_changed:
                      type: string
                      description: Number of lines added and removed
                      example: "+10 -5"
        '400':
          description: Missing required file parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing file parameter
        '500':
          description: CVS Client not initialized or error retrieving history
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: CVS Client not initialized

  /v1/file:
    get:
      summary: Get raw file content at a specific revision
      description: Retrieves the raw content of a file, optionally at a specific revision. If no revision is specified, returns the latest version.
      operationId: getFileContent
      tags:
        - Repository
      parameters:
        - name: file
          in: query
          description: Path to the file in the repository
          required: true
          schema:
            type: string
          example: config.json
        - name: revision
          in: query
          description: Optional specific revision number. If not provided, retrieves the latest version.
          required: false
          schema:
            type: string
          example: "1.3"
      responses:
        '200':
          description: Successfully retrieved file content
          content:
            text/plain:
              schema:
                type: string
                description: Raw file content
                example: |
                  {
                    "app_name": "CVS Proxy",
                    "version": "1.0.0"
                  }
        '400':
          description: Missing required file parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing file parameter
        '500':
          description: CVS Client not initialized or error retrieving file
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Error retrieving content for config.json

  /v1/health:
    get:
      summary: Health check endpoint
      description: Returns the health status of the CVS Proxy service and CVS client initialization status
      operationId: healthCheck
      tags:
        - Health
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Overall service status
                    example: healthy
                  cvs_client:
                    type: string
                    description: CVS client initialization status
                    enum:
                      - initialized
                      - not initialized
                    example: initialized
                  cvs_url:
                    type: string
                    description: Configured CVS repository URL (or "Not configured" if not set)
                    example: ":pserver:username@cvs.example.com:/path/to/repository"

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
      required:
        - error

    FileRevision:
      type: object
      properties:
        revision:
          type: string
          description: CVS revision number
        date:
          type: string
          description: Date and time of the revision
        author:
          type: string
          description: Author of the revision
        state:
          type: string
          description: State of the revision
        lines_changed:
          type: string
          description: Number of lines added and removed

    HealthStatus:
      type: object
      properties:
        status:
          type: string
          description: Service status
        cvs_client:
          type: string
          description: CVS client status
        cvs_url:
          type: string
          description: Configured CVS URL

  securitySchemes:
    cvs_auth:
      type: apiKey
      in: header
      name: X-CVS-Auth
      description: CVS authentication is configured via environment variables (CVS_URL). The API does not implement additional authentication beyond CVS repository configuration.

info:
  x-logo:
    url: https://www.nongnu.org/cvs/
    altText: CVS Logo