keksAccount/public/docs/api.yml

swagger: "2.0"
info:
  description: "API Dokumentation for keksAccount oAuth Service."
  version: "1.0.0"
  title: "KeksAccount"
  contact:
    email: "admin@keks.cloud"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "api.account.keks.cloud"
basePath: "/api/v1"
tags:
  - name: "account"
    description: "The User-Account"
  - name: "user"
    description: "Register and Login to an Account"
schemes:
  - "https"
paths:
  /user/register:
    post:
      tags:
        - "user"
      summary: "Register a new Account"
      description: "Possible if registration is enabled or the request contains a valide invide"
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: formData
          name: username
          description: "Username for the new User"
          required: true
          type: string
        - in: formData
          name: password
          description: "Password for the new User"
          required: true
          type: string
        - in: formData
          name: mail
          description: "A valide E-Mail adress for the User"
          required: true
          type: string
        - in: formData
          name: invite
          description: "If the user have an invite code to create the account"
          required: false
          type: string
        - in: formData
          name: g-recaptcha-response
          description: "If google recaptcha is enabled for account creation this parameter is requierd"
          required: false
          type: string
      responses:
        200:
          description: "User Account crated"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/User'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        400:
          description: "Register disabled, you may can register with an valide invite code"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "Registration disabled"
        422:
          description: "Some of the data ar missing or invalide, see data in the response object for details"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  username:
                    type: array
                    items:
                      type: string
                      example: "The username field is required."
                  password:
                    type: array
                    items:
                      type: string
                      example: "The password field is required."
                  mail:
                    type: array
                    items:
                      type: string
                      example: "The mail field is required."
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "The given data was invalid."
  /user/login:
    post:
      tags:
        - "user"
      summary: "Login to an Account with Username/Passwort"
      description: "Login with Passwort for the keksAccount GUI, dont use this in your Application."
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: formData
          name: username
          description: "Username"
          required: true
          type: string
        - in: formData
          name: password
          description: "Password"
          required: true
          type: string
      responses:
        200:
          description: "Login succesfull"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  access_token:
                    type: "string"
                    description: "Access Token for the user"
                  token_type:
                    type: "string"
                    description: "Typ of the Token"
                    example: ""
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        400:
          description: "Register disabled, you may can register with an valide invite code"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "Registration disabled"
        422:
          description: "Some of the data ar missing or invalide, see data in the response object for details"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  username:
                    type: array
                    items:
                      type: string
                      example: "The username field is required."
                  password:
                    type: array
                    items:
                      type: string
                      example: "The password field is required."
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "The given data was invalid."
  /user/captcha:
    get:
      tags:
        - "user"
      summary: "Return the Captcha Key and Settings"
      description: "Return the Google Recaptcha Key and the list of actions the captcha is enabled/required for"
      produces:
        - "application/json"
      responses:
        200:
          description: "Captcha Informations"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  key:
                    type: "string"
                    description: "Pubplic Recaptcha code"
                  login:
                    type: "boolean"
                    description: "Show captcha if the User want to loging"
                    example: true
                  register:
                    type: "boolean"
                    description: "Show captcha if the User want to register"
                    example: true
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""

  /user/invites:
    get:
      tags:
        - "user"
      summary: "Return information about an invite code"
      description: ""
      produces:
        - "application/json"
      parameters:
        - in: query
          name: code
          description: "The invite code"
          required: true
          type: string
      responses:
        200:
          description: "Captcha Informations"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  usable:
                    type: "boolean"
                    example: true
                    description: "If the value is true the invite code is valide and can be used to register a new account"
                  username:
                    type: "string"
                    description: "If a username is set the user have to use this username for the registration"
                    example: ""
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        404:
          description: "Invite code not found"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "Resource not Found"
  /user/me:
    get:
      tags:
        - "user"
      summary: "Return information about the current User"
      description: ""
      produces:
        - "application/json"
      responses:
        200:
          description: "Found user and return informations"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/User'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        401:
          description: "Not logged in"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"

definitions:
  User:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
        example: 18
      username:
        type: "string"
        example: "testaccount"
      created_at:
        type: "string"
        format: "DateTime"
        example: "2019-07-17T13:37:40.000000Z"
      updated_at:
        type: "string"
        format: "DateTime"
        example: "2019-07-17T13:37:40.000000Z"
      primaryMail:
        type: "string"
        format: "mail"
        example: "mail@example.com"
      status:
        type: "string"
        description: "Account Status"
        example: "active"
        enum:
          - "active"
      inviteCode:
        type: "string"
        example: "sdjfios"
        description: "Invite Code used to register this Account"
      developer:
        type: "boolean"
        example: false
        description: "If the user is a developer Account (Can create new Apps)"
      admin:
        type: "boolean"
        example: false
        description: "If the user is a admin Account"