swagger.yaml

# Example YAML to get you started quickly.
# Be aware that YAML has indentation based scoping.
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "0.5.1"
  title: PMS
schemes:
  - http
  - https

# during dev, should point to your local machine
# host: pms.wlbd.nl
host: pms.zaphod

# basePath prefixes all resource paths
basePath: /api

consumes:
  - application/json
produces:
  - application/json

paths:
  /login:
    post:
      description: Login into API
      parameters:
        - name: loginRequest
          in: body
          required: true
          schema:
            type: object
            properties:
              user:
                type: string
              password:
                type: string
      responses:
        200:
          description: Login success
          schema:
            $ref: '#/definitions/LoginResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /people:
    get:
      description: |
        Returns all people
        Gets `Person` objects.
      responses:
        # Response code
        200:
          description: Returns a resultobject
          # A schema describing your response object.
          # Use JSON Schema format
          schema: 
            $ref: '#/definitions/PeopleResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
    post:
      description: Add a new `Person` object
      parameters:
        - name: newPerson
          in: body
          required: true
          schema:
            $ref: "#/definitions/Person"
      responses:
        200:
          description: Returns the new person
          schema:
            $ref: "#/definitions/PeopleResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
  /people/{people_id}:
    get:
      description: Get a single `person`
      parameters:
        - in: path
          name: people_id
          description: the id of the `Person` being fetched
          required: true
          type: integer
      responses:
        200:
          description: Successfull
          schema: 
            $ref: '#/definitions/PeopleResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
    put:
      description: Update a person
      parameters:
        - in: path
          name: people_id
          description: the id of the `Person` being updated
          required: true
          type: integer
        - in: body
          name: PersonUpdate
          required: true
          schema:
            $ref: "#/definitions/Person"
      responses:
        200:
          description: Successfull
          schema: 
            $ref: '#/definitions/PeopleResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
  /people/{people_id}/ref:
    post:
      description: Add a new ref, depending on ref_type, (eg. it creates a link between people and roles)
      parameters:
        - in: path
          name: people_id
          description: the id of the `Person` being changed
          required: true
          type: integer
        - in: body
          name: resource
          required: true
          schema:
            $ref: '#/definitions/ResourceReference'
      responses:
        200:
          description: Successfull
          schema: 
            $ref: '#/definitions/PeopleResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /roles:
    get:
      description: Returns all roles
      responses:
        200:
          description: Successfull response, with roles.
          schema:
            $ref: "#/definitions/RolesResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
    post:
      description: Creates a new `Role`
      parameters:
        - name: New Role
          in: body
          required: true
          schema:
            $ref: "#/definitions/Role"
      responses:
        200:
          description: Returns the new role
          schema:
            $ref: "#/definitions/RolesResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
  /roles/{roles_id}:
    get:
      description: Get a single `Role`
      parameters:
        - in: path
          name: roles_id
          description: the id of the `Role` being fetched
          required: true
          type: integer
      responses:
        200:
          description: Successfull
          schema:
            $ref: "#/definitions/RolesResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
    put:
      description: Update a `Role`
      parameters:
        - in: path
          name: roles_id
          description: the id of the `Role` being updated
          required: true
          type: integer
        - in: body
          name: RoleUpdate
          required: true
          schema:
            $ref: "#/definitions/Role"
      responses:
        200:
          description: Successfull
          schema:
            $ref: "#/definitions/RolesResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
  /roles/{roles_id}/ref:
    post:
      description: Add a new ref, depending on ref_type, (eg. it creates a link between people and roles)
      parameters:
        - in: path
          name: roles_id
          description: the id of the `Role` being updated
          required: true
          type: integer
        - in: body
          name: resource
          required: true
          schema:
            $ref: '#/definitions/ResourceReference'
      responses:
        200:
          description: Successfull
          schema: 
            $ref: '#/definitions/RolesResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'

  /fields:
    get:
      description: Return all schemas
      responses:
        200:
          description: Successfull response, with fields.
          schema:
            $ref: '#/definitions/FieldsResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
            
  /fields/{resource_name}:
    get:
      description: Returns a schema
      parameters:
        - in: path
          required: true
          name: resource_name
          description: The name of the resource type
          type: string
      responses:
        200:
          description: Successfull response, with a single schema.
          schema:
            $ref: '#/definitions/FieldsResponse'
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
    post:
      description: Create new field
      parameters:
        - in: path
          required: true
          name: resource_name
          description: The name of the resource type
          type: string
      responses:
        200:
          description: Successfull
          schema:
            $ref: "#/definitions/FieldsResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'
          
    put:
      description: Update the field
      parameters:
        - in: path
          required: true
          name: resource_name
          description: The name of the resource type
          type: string
      responses:
        200:
          description: Successfull
          schema:
            $ref: "#/definitions/FieldsResponse"
        400:
          description: An error has occurred on the server.
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/ErrorResponse'


definitions:
  Person:
    title: Person
    type: object
    # required:
    #   - nickname
    #   - email
    properties:
      nickname:
        type: string
      email:
        type: string
        format: email
      birthdate:
        type: string
        format: date
      firstname:
        type: string
      infix:
        type: string
      
      roles:
        type: array
        items:
          $ref: '#/definitions/ResourceReference'
    additionalProperties: true
    example:
      nickname: Pietje
      firstname: Pieter
      email: piet@example.com
      birthdate: 1916-05-04T12:21:25.497+00:00
      roles:
        - '\$ref': '/roles/3'
        - '\$ref': '/roles/4'

  ResourceReference:
    type: object
    properties:
      $ref: 
        type: string
        description: JsonPath pointing to pms resource
    required:
      - $ref

  Role:
    title: Role
    type: object
    properties:
      name:
        type: string
      description:
        type: string
    additionalProperties: true
    example:
      name: Bestuur
      description: Het bestuur
      members:
        - '\$ref': '/member/13'
        - '\$ref': '/member/42'

  Field:
    type: object
    properties:
      type:
        type: string
      title:
        type: string

  LoginResponse:
    type: object
    required:
      - token
      - permissions

    properties:
      token:
        type: string
      permissions:
        $ref: '#/definitions/SelfPermissions'

  SelfPermissions:
    type: object

  ResourceSchema:
    type: object
    properties:
      properties:
        type: object
        additionalProperties:
          $ref: '#/definitions/Field'
      form:
        type: array
        items: 
          type: object
          parameters:
            fields:
              type: array
              description: Rows of fieldsets
              items:
                type: array
                description: An array of fields
                items:
                  type: string
                  description: A reference to a field
            title:
              type: string
      header:
        type: array
        items: 
          type: string
      required:
        type: array
        items: 
          type: string
  
  PeopleResponse:
    type: object
    properties:
      people:
        type: object
        additionalProperties:
          allOf: 
            - $ref: '#/definitions/BaseResourceResponse'
            - $ref: '#/definitions/Person'
      roles:
        type: object
        additionalProperties:
          allOf: 
            - $ref: '#/definitions/BaseResourceResponse'
            - $ref: '#/definitions/Role'
    required:
      - people

  RolesResponse:
    type: object
    properties:
      people:
        additionalProperties:
          allOf: 
            - $ref: '#/definitions/BaseResourceResponse'
            - $ref: '#/definitions/Person'
      roles:
        additionalProperties:
          allOf: 
            - $ref: '#/definitions/BaseResourceResponse'
            - $ref: '#/definitions/Role'
    required:
      - roles

  FieldsResponse:
    type: object
    properties:
      fields:
        additionalProperties:
          $ref: '#/definitions/ResourceSchema'
    required:
      - fields

  BaseResourceResponse:
    type: object
    description: |
      The base object structure for every api base resource.
      Contains an id and a gid, and some timestamps
    properties:
      id:
        type: integer
        description: The unique id for its type.
      gid:
        type: integer
        description: Globally unique version identifier
      valid_from:
        type: string
        format: date-time
      valid_till:
        type: 'null'
      modified_by:
        type: integer
    required:
      - id
      - gid

  ErrorResponse:
    title: Error
    type: object
    properties:
      error:
        type: string