swagger.yml

swagger: "2.0"
info:
  description: |
    Here is a API to handle Redmine's site wide banner.
    Now prototype version.
  version: "1.0.0-α"
  title: "GlobalBanner API"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "akiko.pusu@gmail.com"
schemes:
  - "http"
  - "https"
host: "localhost:3000"
paths:
  /banners/api/global_banner.json:
    get:
      summary: "Show Global Banner setting"
      description: |
        Show Global Banner setting as JSON format stored in a settings table.

        Only Redmine Administrator or user assigned to group named **"GlobalBanner_Admin"** can use this api.
        The way to authenticate follows Redmine itself.
        - Exp. User parameter ?key=YOUR_API_KEY or HTTP Header: X-Redmine-API-Key and so on.
        - Please see: http://www.redmine.org/projects/redmine/wiki/Rest_api#Authentication
      parameters:
      - name: "X-Redmine-API-Key"
        in: "header"
        description: "Your API KEY"
        required: true
        type: "string"
      responses:
        200:
          description: "Response in success"
          schema:
            $ref: '#/definitions/global_banner_body'
        401:
          description: "Response in Unauthorized."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                example: "401"
              message:
                type: "string"
                example: "Unauthorized"
    put:
      summary: "Update Global Banner setting"
      description: |
        Update Global Banner setting as JSON format stored in a settings table.

        Only Redmine Administrator or user assigned to group named **"GlobalBanner_Admin"** can use this api.
        The way to authenticate follows Redmine itself.
        - Exp. User parameter ?key=YOUR_API_KEY or HTTP Header: X-Redmine-API-Key and so on.
        - Please see: http://www.redmine.org/projects/redmine/wiki/Rest_api#Authentication
      consumes:
        - application/json
      parameters:
        - name: "X-Redmine-API-Key"
          in: "header"
          description: "Your API KEY"
          required: true
          type: "string"
        - in: body
          name: global_banner
          description: Data to update Global Banner.
          required: true
          schema:
            $ref: '#/definitions/global_banner_body'
      responses:
        200:
          description: "Response in success."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                example: "OK"
              message:
                type: "string"
                example: "updatig the global banner"
        401:
          description: "Response in Unauthorized."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                example: "401"
              message:
                type: "string"
                example: "Unauthorized"
        500:
          description: "Response in internal error."
          schema:
            type: "object"
            properties:
              status:
                type: "string"
                example: "500"
              message:
                type: "string"
                example: "Internal Server Error"

definitions:
  global_banner_body:
    type: "object"
    properties:
      global_banner:
        $ref: "#/definitions/Globel_banner" # Storeを呼び出す
  Globel_banner:
    type: "object"
    required:
      - banner_description
      - display_part
      - type
    properties:
      banner_description:
        type: string
        example: "Message for Global Banner"
      display_for:
        type: "string"
        example: "all"
        enum: [all, anonymous, authenticated]
        description: >
            Display for:
             * `all` - For all users
             * `anonymous` - For anonymous users
             * `authenticated` - For authenticated users
      display_part:
        type: "string"
        example: "both"
        enum: [header, footer, both]
        description: >
            Display part:
             * `header` - Display banner on the top
             * `footer` - Display banner on the bottom
             * `both`   - Display banner both header and footer
      enable:
        type: "string"
        example: "true"
        enum: [true, false]
      end_hour:
        type: integer
        example: 16
        maximum: 23
      end_min:
        type: integer
        example: 31
        maximum: 59
      end_ymd:
        type: "string"
        example: "2019-08-21"
      related_link:
        type: "string"
        example: "http://localhost:3000/news"
      start_hour:
        type: integer
        example: 16
        maximum: 23
      start_min:
        type: integer
        example: 31
        maximum: 59
      start_ymd:
        type: "string"
        example: "2019-08-20"
      type:
        type: "string"
        example: "info"
        enum: [info, warn, alert, normal, nodata]
        description: >
            type:
             * `info` - Info style. (Pale blue)
             * `warn` - Warning style. (Yellow)
             * `alert`   - Alert style. (Pale red)
             * `normal`  - White and without status icon.
      use_timer:
        type: "string"