openapi.yaml

openapi: 3.0.1
info:
  title: Example Chat Service
  description: |
    Simple service for chatting. The API has operations for:
    - getting all messages
    - creating a new message
    - getting messages in pages, i.e. last 20 messages or previous 20 messages
    - getting a specific message by its id

    The description of the API in OpenAPI format is generated by
    the tool [SpringDoc v2](https://springdoc.org/) from annotated Java classes,
    mainly the controller class
    [ChatRestController](https://github.com/martin-kuba/muni-chat-service/blob/main/chat-server/src/main/java/cz/muni/chat/server/rest/ChatRestController.java)
    and the DTO classes in
    [cz.muni.chat.server.facade](https://github.com/martin-kuba/muni-chat-service/tree/main/chat-server/src/main/java/cz/muni/chat/server/facade)
    package.
  contact:
    name: Martin Kuba
    url: https://www.muni.cz/lide/3988-martin-kuba
    email: makub@ics.muni.cz
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: "1.1"
servers:
- url: "{scheme}://{server}:{port}"
  description: my server
  variables:
    scheme:
      default: http
      enum:
      - http
      - https
    server:
      default: localhost
    port:
      default: "8080"
tags:
- name: Chat
  description: microservice for chat
paths:
  /api/messages:
    get:
      tags:
      - Chat
      summary: Get all messages
      description: |
        Returns an array of objects representing chat messages, ordered from the newest to the oldest.
        Each message must have a **text** and **timestamp**, and optionally may have an **author**,
        a **text color** and a **background color**.
        It is possible to use [MarkDown](https://www.markdownguide.org/) in descriptions.
      operationId: getAllMessages
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ChatMessage"
    post:
      tags:
      - Chat
      summary: Create a new message
      description: |
        Receives data both in request body and as URL parameter and stores them as a new message.
        Returns the new message as its response.
      operationId: createMessage
      parameters:
      - name: author
        in: query
        required: false
        schema:
          type: string
      - name: User-agent
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewChatMessageRequest"
        required: true
      responses:
        "201":
          $ref: "#/components/responses/SingleMessageResponse"
        "400":
          description: input data were not correct
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
  /api/paged:
    get:
      tags:
      - Chat
      summary: Paged messages
      description: |
        Returns a page of chat messages.
        The parameter `page` specifies zero-based index of the requested page,
        the parameter `size` specifies the size of the page.
        The parameter `sort` is ignored, sorting is always from the newest to the oldest.
      operationId: paged
      parameters:
      - name: page
        in: query
        description: Zero-based page index (0..N)
        required: false
        schema:
          minimum: 0
          type: integer
          default: 0
      - name: size
        in: query
        description: The size of the page to be returned
        required: false
        schema:
          minimum: 1
          type: integer
          default: 20
      - name: sort
        in: query
        description: "Sorting criteria in the format: property,(asc|desc). Default\
          \ sort order is ascending. Multiple sort criteria are supported."
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PagedModelChatMessage"
  /api/message/{id}:
    get:
      tags:
      - Chat
      summary: Returns identified message
      description: Looks up a message by its id.
      operationId: getMessage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          $ref: "#/components/responses/SingleMessageResponse"
        "404":
          description: message not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"
components:
  schemas:
    ErrorMessage:
      title: error message
      type: object
      properties:
        timestamp:
          type: string
          description: time in ISO format
          format: date-time
          example: 2022-12-21T18:52:10.757Z
        status:
          type: integer
          description: HTTP status code
          format: int32
          example: 404
        error:
          type: string
          description: HTTP status text
          example: Not Found
        message:
          type: string
          description: reason for error
          example: entity not found
        path:
          type: string
          description: URL path
          example: /api/message/1
      description: response body for HTML statuses
    BackgroundColorEnum:
      title: background color
      type: string
      description: enumeration of allowed background colors
      enum:
      - lightgray
      - white
      - aquamarine
      - lightyellow
      - lightblue
      - "#ffe4c4"
    NewChatMessageRequest:
      required:
      - text
      type: object
      properties:
        text:
          type: string
          description: text of message
          example: Hello! 😀
        textColor:
          type: string
          description: HTML color name or RGB hex code
          example: black
          enum:
          - black
          - blue
          - darkgrey
        backgroundColor:
          $ref: "#/components/schemas/BackgroundColorEnum"
      description: |
        Object for requesting new message.
        **Text** of the message must be located in the request body because URLs are limited in size.
        See [What is the maximum length of a URL in different browsers?](https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers)
    ChatMessage:
      title: chat message
      required:
      - id
      - text
      - timestamp
      type: object
      properties:
        id:
          type: string
          description: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        timestamp:
          type: string
          description: time of creation
          format: date-time
          example: 2022-12-22T12:04:04.493908908+01:00
        text:
          type: string
          description: text of message
          example: Hello! 😀
        author:
          type: string
          description: author of message
          example: John
        textColor:
          type: string
          description: HTML color name or RGB hex code
          example: black
        backgroundColor:
          $ref: "#/components/schemas/BackgroundColorEnum"
      description: represents a message in a chat
    PageMetadata:
      type: object
      properties:
        size:
          type: integer
          format: int64
        number:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
    PagedModelChatMessage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/ChatMessage"
        page:
          $ref: "#/components/schemas/PageMetadata"
  responses:
    SingleMessageResponse:
      description: response containing a single message
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ChatMessage"
      links:
        link_to_getMessage:
          operationId: getMessage
          parameters:
            id: $response.body#/id
          description: |
            The `id` value returned in the response can be used as
            the `id` parameter in `GET /message/{id}`.