api.yml

openapi: "3.0.3"

tags:
  - name: Roadmap
    description: Operation is related to Roadmaps
  - name: Create
    description: Operation is used to create a single new entity
  - name: Retrieve
    description: Operation is used to retrieve a single entity

info:
  version: 0.0.1
  title: Roadmapper API
  description: API for Roadmapper
  termsOfService: https://docs.rdmp.app/terms/
  contact:
    name: Roadmapper Team
    email: team@rdmp.app
    url: https://rdmp.app
  license:
    name: ISC
    url: https://opensource.org/licenses/ISC

servers:
  - url: https://rdmp.app/api
  - url: http://localhost:9877/api

paths:
  /roadmaps:
    post:
      description: Creates a new roadmap
      operationId: createRoadmap
      tags:
        - Roadmap
        - Create
      requestBody:
        description: Roadmap to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoadmapRequest'
      responses:
        '201':
          description: Roadmap create success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoadmapResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'

  /roadmaps/{roadmap_id}:
    get:
      description: Retrieves a roadmap
      operationId: getRoadmap
      tags:
        - Roadmap
        - Retrieve
      parameters:
        - name: roadmap_id
          in: path
          description: ID of roadmap to update
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Roadmap response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoadmapResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'

components:
  schemas:
    RoadmapRequest:
      allOf:
        - $ref: '#/components/schemas/Roadmap'

    RoadmapResponse:
      allOf:
        - $ref: '#/components/schemas/Roadmap'
      properties:
        id:
          type: string
      required:
        - id

    Roadmap:
      properties:
        prev_id:
          type: string
        title:
          type: string
        date_format:
          type: string
        base_url:
          type: string
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/Milestone'
      required:
        - title
        - date_format

    Project:
      properties:
        indentation:
          type: integer
          minimum: 0
        title:
          type: string
        dates:
          $ref: '#/components/schemas/Dates'
        percentage:
          type: integer
          minimum: 0
          maximum: 100
        urls:
          type: array
          items:
            type: string
        milestone:
          type: integer
          minimum: 1
      required:
        - title

    Dates:
      required:
        - start_at
        - end_at
      properties:
        start_at:
          type: string
        end_at:
          type: string

    Milestone:
      required:
        - title
      properties:
        title:
          type: string
        urls:
          type: array
          items:
            type: string

    Problem:
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type.  When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: 'about:blank'
          example: 'https://rdmp.app/problem/constraint-violation'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in English and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized); example: Service Unavailable
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
      required:
        - type
        - title