Team definition

definition.yaml

openapi: '3.0.0'
info:
  title: API Teams
  version: '1.0'
  description: API for managing Teams
  contact:
    name: Elio Capelati Junior
    email: eliocapelati@gmail.com
servers:
  - url: 'http://localhost:8080/v1'
    description: Local Development
  - url: 'https://api.server.com.br/v1'
    description: Production Server
paths:
  /teams:
    post:
      tags:
        - Teams
      security:
        - bearerAuth: []
      summary: Create a teams
      description: Create a team and attach to the current user in the auth token
      operationId: createTeam
      requestBody:
        $ref: "#/components/requestBodies/CreateTeamRequest"
      responses:
        201:
          $ref: "#/components/responses/CreateTeamResponse"
        400:
          $ref: "#/components/responses/BadRequestErrorInfo"
        401:
          $ref: "#/components/responses/UnauthorizedErrorInfo"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorInfo"
    get:
      tags:
        - Teams
      security:
        - bearerAuth: [ ]
      summary: Get all teams paged
      description: Get all teams attached to current user
      operationId: getTeams
      parameters:
        - $ref: "#/components/parameters/Pageable"
      responses:
        200:
          $ref: "#/components/responses/PagedTeamResponse"
        401:
          $ref: "#/components/responses/UnauthorizedErrorInfo"
        404:
          $ref: "#/components/responses/NotFoundErrorInfo"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorInfo"
  /teams/{teamId}:
    get:
      tags:
        - Teams
      security:
        - bearerAuth: [ ]
      summary: Get a team by id
      description: Get a team by id
      operationId: getTeamById
      parameters:
        - $ref: "#/components/parameters/TeamId"
      responses:
        200:
          $ref: "#/components/responses/TeamResponse"
        404:
          $ref: "#/components/responses/NotFoundErrorInfo"
        401:
          $ref: "#/components/responses/UnauthorizedErrorInfo"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorInfo"
    patch:
      tags:
        - Teams
      security:
        - bearerAuth: []
      summary: Update a team by id
      description: Update a team attached to the current user in the auth token
      operationId: update
      parameters:
        - $ref: "#/components/parameters/TeamId"
      requestBody:
        $ref: "#/components/requestBodies/PatchTeamRequest"
      responses:
        204:
          description: "Updated"
        400:
          $ref: "#/components/responses/BadRequestErrorInfo"
        401:
          $ref: "#/components/responses/UnauthorizedErrorInfo"
        404:
          $ref: "#/components/responses/NotFoundErrorInfo"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorInfo"

components:
  ###Parameters section
  parameters:
    TeamId:
      name: teamId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    Pageable:
      name: pageable
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/PageableRequest"

  ### Responses section
  responses:
    CreateTeamResponse:
      description: Successful created a team
      headers:
        Location:
          schema:
            type: string
          example: "/teams/{id}"
          description: Path to get the created team
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TeamResponse"
    TeamResponse:
      description: Team Response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TeamResponse"

    PagedTeamResponse:
      description: Paged team reaponse
      content:
        application/json:
          schema:
            properties:
              content:
                type: array
                items:
                  $ref: "#/components/schemas/TeamResponse"
            allOf:
              - $ref:  "#/components/schemas/PageableResponse"

    BadRequestErrorInfo:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    NotFoundErrorInfo:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    UnauthorizedErrorInfo:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
    ServiceUnavailableErrorInfo:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"

  ### Request Body section
  requestBodies:
    CreateTeamRequest:
      description: Create a team considering a uniq name for current user
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/TeamProperties"
              - $ref: "#/components/schemas/TeamRequiredProperties"

    PatchTeamRequest:
      description: Update a team
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/TeamProperties"


  ### Schemas section
  schemas:
    Id:
      type: string
      description: Id spec used in the entire API
      example: "507f1f77bcf86cd799439011"
    Name:
      type: string
      description: Representation of a name
      minLength: 2
      example: "John"    
    TeamProperties:
      type: object
      properties:
        teamName:
          $ref: "#/components/schemas/Name"
        description:
          type: string
    TeamRequiredProperties:
      type: object
      required:
        - teamName
        - description
    TeamId:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Id"
    TeamResponse:
      type: object
      allOf:
        - $ref: "#/components/schemas/TeamProperties"
        - $ref: "#/components/schemas/TeamId"

    PageableResponse:
      description: Default pageable response
      type: object
      properties:
        totalPages:
          type: integer
          description: Total pages
          example: 1
        totalElements:
          type: integer
          description: Total number of elements
          example: 1
        size:
          type: integer
          description: Sum of elements in content
          example: 1

    PageableRequest:
      description: Pageable query parameters
      type: object
      properties:
        page:
          type: integer
          default: 0
        size:
          type: integer
          default: 100

    #Error handling
    Violation:
      type: object
      properties:
        fieldName:
          type: string
          example: "userName"
        message:
          type: string
          example: "Cant be null"
    ErrorInfo:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: "Date Time in UTC"
        status:
          type: integer
          format: int32
        error:
          type: string
        message:
          type: string
        path:
          type: string
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Violation"

  ### Security Schemes section
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

### Tags
tags:
  - name: Teams
    description: Manage teams