linux-odyssey/server/api/swagger.yaml

---
openapi: 3.0.0
info:
  title: Session API
  description: Linux Odyssey API
  contact:
    email: wancat@wancat.cc
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: /
tags:
  - name: admins
    description: Secured Admin-only calls
  - name: developers
    description: Operations available to regular developers
paths:
  /sessions:
    get:
      tags:
        - signed-in
      summary: list existing sessions of current user
      responses:
        '200':
          description: list of existing session
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
      security:
        - BearerAuth: []
    post:
      tags:
        - signed-in
      summary: create a new session for current user
      parameters:
        - name: exercise_id
          in: query
          description: pass the exercise id
          required: true
          style: form
          explode: true
          schema:
            type: string
      responses:
        '201':
          description: session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
      security:
        - BearerAuth: []
  /sessions/{session_id}:
    get:
      tags:
        - signed-in
      summary: get a specific session of current user by ID
      parameters:
        - name: session_id
          in: path
          description: ID of the session to retrieve
          required: true
          style: simple
          explode: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: the session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          description: cannot find specific session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
      security:
        - BearerAuth: []
    delete:
      tags:
        - signed-in
      summary: delete a specific session by ID
      parameters:
        - name: session_id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Session successfully deleted
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
      security:
        - BearerAuth: []
  /inventory:
    get:
      tags:
        - developers
      summary: searches inventory
      description: |
        By passing in the appropriate options, you can search for
        available inventory in the system
      operationId: searchInventory
      parameters:
        - name: searchString
          in: query
          description: pass an optional search string for looking up inventory
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: skip
          in: query
          description: number of records to skip for pagination
          required: false
          style: form
          explode: true
          schema:
            minimum: 0
            type: integer
            format: int32
        - name: limit
          in: query
          description: maximum number of records to return
          required: false
          style: form
          explode: true
          schema:
            maximum: 50
            minimum: 0
            type: integer
            format: int32
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryItem'
        '400':
          description: bad input parameter
    post:
      tags:
        - admins
      summary: adds an inventory item
      description: Adds an item to the system
      operationId: addInventory
      requestBody:
        description: Inventory item to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryItem'
      responses:
        '201':
          description: item created
        '400':
          description: 'invalid input, object invalid'
        '409':
          description: an existing item already exists
  /register:
    post:
      summary: Register a new user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/register_body'
        required: true
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_201'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_1'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_409'
  /login:
    post:
      summary: Log in a user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/login_body'
        required: true
      responses:
        '200':
          description: User logged in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400_2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401_1'
  /profile:
    tags:
      - signed-in
    get:
      summary: Get the profile of current logged-in user
      responses:
        '200':
          description: Get user's profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      security:
        - BearerAuth: []
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
          example: alex
        email:
          type: string
          format: email
    Exercise:
      type: object
      properties:
        name:
          type: string
        introduction:
          type: string
    Session:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        exercise_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        terminals:
          type: array
          items:
            type: string
        graphs:
          $ref: '#/components/schemas/TreeNode'
        progress:
          type: array
          items:
            $ref: '#/components/schemas/Progress'
        hints:
          type: array
          items:
            $ref: '#/components/schemas/Hint'
    TreeNode:
      type: object
      properties:
        name:
          type: string
        display:
          type: boolean
        children:
          type: array
          items:
            $ref: '#/components/schemas/TreeNode'
    Progress:
      type: object
      properties:
        name:
          type: string
        finished_at:
          type: string
          format: date-time
        skipped_at:
          type: string
          format: date-time
    Hint:
      type: object
      properties:
        name:
          type: string
        content:
          type: string
        source:
          type: string
    InventoryItem:
      required:
        - id
        - manufacturer
        - name
        - releaseDate
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        name:
          type: string
          example: Widget Adapter
        releaseDate:
          type: string
          format: date-time
          example: 2016-08-29T09:12:33.001Z
        manufacturer:
          $ref: '#/components/schemas/Manufacturer'
    Manufacturer:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          example: ACME Corporation
        homePage:
          type: string
          format: url
          example: https://www.acme-corp.com
        phone:
          type: string
          example: 408-867-5309
    inline_response_400:
      type: object
      properties:
        message:
          type: string
    inline_response_404:
      type: object
      properties:
        message:
          type: string
          example: Session not found.
    inline_response_401:
      type: object
      properties:
        message:
          type: string
          example: Unauthorized.
    register_body:
      type: object
      properties:
        username:
          type: string
        email:
          type: string
        password:
          type: string
    inline_response_201:
      type: object
      properties:
        message:
          type: string
          example: User created successfully
    inline_response_400_1:
      type: object
      properties:
        message:
          type: string
          example: 'Missing username, email or password'
    inline_response_409:
      type: object
      properties:
        message:
          type: string
          example: User already exists
    login_body:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
    inline_response_200:
      type: object
      properties:
        message:
          type: string
          example: Login successful
        token:
          type: string
          description: Access token
    inline_response_400_2:
      type: object
      properties:
        message:
          type: string
          example: Missing username or password
    inline_response_401_1:
      type: object
      properties:
        message:
          type: string
          example: Incorrect username or password
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT