swagger.yaml

swagger.yaml

swagger: '2.0'

info:
  version: 0.0.1
  title: Streuth Profile API

basePath: /api

tags:
  - name: public
    description: Public information endpoints
  - name: user
    description: Operations relating to the logged-in user themselves

#-------------------------------------------------------------------------------
paths:

  /health-check:
    get:
      summary: Possibly slow check of system health status
      description: Returns single-level hash of checks and statuses
      operationId: Root::health_check
      produces:
        - application/json
      tags:
        - public
      responses:
        200:
          description: Successful operation, all systems operational.
        503:
          description: Something is wrong

  /ping:
    get:
      summary: Quick check to see if the app is running
      description: Returns ok
      operationId: Root::ping
      produces:
        - text/plain
      tags:
        - public
      responses:
        200:
          description: Successful operation

  /swagger.json:
    get:
      summary: Returns the swagger spec
      operationId: Root::swagger
      produces:
        - application/json
      tags:
        - public
      responses:
        200:
          description: Successful operation

  /version.json:
    get:
      summary: Returns the current version information
      operationId: Root::version
      produces:
        - application/json
      tags:
        - public
      responses:
        200:
          description: Successful operation

#-------------------------------------------------------------------------------
# User paths

  /user:
    get:
      summary: Quick check to see if user is logged in.
      operationId: User::get
      produces:
        - application/json
      tags:
        - user
      responses:
        200:
          description: Successful operation
          schema:
            $ref: "#/definitions/User"

  /user/details:
    get:
      summary: Returns full information about the logged-in user.
      operationId: User::getDetails
      produces:
        - application/json
      tags:
        - user
      responses:
        200:
          description: Successful operation
          schema:
            $ref: "#/definitions/UserDetails"

  /user/names:
    put:
      summary: Change the user's given name and/or surname.
      operationId: User::updateName
      produces:
        - application/json
      tags:
        - user
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: "#/definitions/UserNames"
      responses:
        200:
          description: Successful operation
          schema:
            $ref: "#/definitions/UserNames"


#-------------------------------------------------------------------------------
definitions:

  Site:
    type: object
    properties:
      display:
        type: string
      name:
        type: string
    required:
      - display
      - name

  User:
    type: object
    properties:
      username:
        type: string
      uuid:
        type: string
    required:
      - username
      - uuid

  UserDetails:
    type: object
    properties:
      account_locked:
        type: integer
      attributes:
        type: array
        items:
          type: string
      backup_email:
        type: string
      email:
        type: string
      full_name:
        type: string
      given_name:
        type: string
      groups:
        type: array
        items:
          type: string
      managed_attributes:
        type: array
        items:
          type: string
      mobile:
        type: string
      password_changed:
        type: string
        format: date-time
        x-nullable: true
      password_expires:
        type: string
        format: date-time
      sites:
        type: array
        items:
          $ref: '#/definitions/Site'
      surname:
        type: string
      username:
        type: string
      uuid:
        type: string
    required:
      - attributes
      - backup_email
      - email
      - full_name
      - given_name
      - groups
      - managed_attributes
      - mobile
      - password_changed
      - password_expires
      - sites
      - surname
      - username
      - uuid

  UserNames:
    type: object
    properties:
      given_name:
        type: string
      surname:
        type: string
    required:
      - given_name
      - surname