README.md

    Написание контроллеров OpenApi

    Общая информация написания

    1. Описание ендпоинта сопровождается стандартом OpenApi, где:

      • Пример написания ендпоинта

        /api/v1/order/{id}:
          post:
              tags:
                 - OrderController
              operationId: createOrder
              requestBody:
                 content:
                    application/json:
                       schema:
                          $ref: '../dto/OrderRq.yml#/OrderRq'
              responses:
                 "200":
                    description: OK
                    content:
                       application/json:
                          schema:
                          $ref: '../dto/OrderRq.yml#/OrderRq'
                 "400":
                    $ref: '../dto/error/400.yml#/400'
                 "403":
                    $ref: '../dto/error/403.yml#/403'
                 "404":
                    $ref: '../dto/error/404.yml#/404'
          get:
          ...
        
      • Строка /api/v1/order/{id} отвечает за сам путь ендпоинта
      • Строка post отвечает за метод запроса, если методов запроса у ендпоинта несколько, то следующие ендпоинты указываются в данном блоке, но начиная с самого метода запроса и с соблюдением табуляции. Как пример предпоследняя строка get
      • Строка tags отвечает за наименование интерфейса контроллера, который будет создан для реализации в подключаемом классе
      • Строка - OrderController само наименование интерфейса контроллера через тире
      • Строка operationId отвечает за наименование самого метода для реализации
      • Строка requestBody отвечает за принимаемые аргументы в метод, $ref: '../dto/OrderRq.yml#/OrderRq' ссылается на файл с описанием дто
      • Строка responses отвечает за варианты ответа ендпоинта, в ней описывается все ответы данного ендпоинта, где:
        • 200 - код ответа,
        • description - описание ответа,
        • content - возвращаемый контент, выступающий в качестве возвращающего параметра метода
        • application/json тип ответа,
        • $ref: '../dto/OrderRq.yml#/OrderRq' ссылка до дто (вернет саму дто), которую должен вернуть по запросу ендпоинта
    2. После написания всех енддпоинтов в классе контроллера, надо указать все пути ендпоинтов в файле spec.yaml данного модуля

      • В файле spec.yaml в параметрах paths указывается путь ендпоинтов и ссылка на контроллер с данными ендпоинтами и указание пути - / через ~1, как на примере ниже

        /api/v1/order/{id}:
          $ref: "controller/OrderController.yml#/~1api~1v1~1order~1{id}"
        
      • Данная запись заходит в описание и собирает все методы запроса данного ендпоинта

    Написание дтошек OpenApi

    Общая информация написания

    1. При написании дто следует помнить, что будут сгенерированы все дто участвующие в цепочке, которые присутствуют в дто, которая была указана в контроллере
    2. Дто которая не участвует в созданом контроллере для кодогенерации можно добавить в следующее место spec.yaml:

        components:
            schemas:
               OrderRs:
                  $ref: "dto/OrderRs.yml#/OrderRs"
               OrderRq:
                  $ref: "dto/OrderRq.yml#/OrderRq"
      
    3. Описание переменных дто сопровождается стандартом OpenApi, где:

        OrderRs:
            type: object
            properties:
               fieldString:
                  type: string
                  maxLength: 50
               fieldUUID:
                  type: string
                  format: uuid
               fieldInteger:
                  type: integer
                  format: int32
                  minimum: 0
                  maximum: 10
                  default: 1
               fieldLong:
                  type: integer
                  format: int64
               fieldBoolean:
                  type: boolean
               fieldDate:
                  type: string
                  format: date
               fieldLocalDate:
                  type: string
                  format: date
               fieldOffsetDateTime:
                  type: string
                  format: date-time
               fieldListString:
                  type: array
                  maxItems: 999
                  items:
                     type: string (либо указание любого типа или $ref 'ссылка на любую дто', но без type)
               fieldSetString:
                  type: array
                  uniqueItems: true
                  items:
                     type: string
               fieldBigDecimal:
                  type: number
      
      • Строка OrderRs напзвание дто
      • Строка type: object отвечает за тип объекта
      • Строка properties отвечает за сами переменные в дто
      • Строка fieldString и ниже это сами названия переменных
      • Строка type в переменных отвечает за установку типа переменной в некоторых случая требуется указать еще format
      • Переменным может потребоваться проставить значения по умолчанию, для этого используется default: "text" / true / 20 остальные валидационные параметры рекомендуется указывать через вставку ниже (так как в данном случае возможно полностью настроить все параметры аннотации)
      • Для валидации могут потребоваться некоторые аннотации, ниже представлен способ добавления 1 или более аннотаций для переменных x-field-extra-annotation: " @lombok.Builder.Default @javax.validation.constraints.Pattern(regexp = \**(?i)(asc|desc)&\*)"
      • Когда создается list/set нужно обязательно данную переменную указывать в теге required, в ином случае переменная не будет иметь реализацию ArrayList или HashSet. Пример ниже

        OrderRq:
          type: object
          required:
               - name
               - deliveryType
               - count
               - messages
          properties:
               name:
                  type: string
                  maxLength: 50
               deliveryType:
                  $ref: 'enum/DeliveryType.yml#/DeliveryType'
               count:
                  type: integer
                  minimum: 0
                  maximum: 10
                  default: 1
               messages:
                  type: array
                  items:
                     type: string
        
      • Тэг required нужен для создания конструктора с указанными переменными
    4. Фрагмент наследования приведен ниже, обязательно нужно соблюдать все табуляции:

          ExtendsExample:
             allOf:
                - $ref: 'OrderRs.yml#/OrderRs'
                - type: object
                  properties:
                     newProperty:
                        type: string
      
    5. Создание енамок можно осуществить двумя способами:

      • первый способ создания констант в енамке без значений

        DeliveryType:
          type: string
          enum:
               - PICKUP
               - COURIER_DELIVERY
               - PEDESTALS
        
      • второй способ создания констант в енамке с значениями

        DeliveryType:
          type: string
          enum:
               - САМОВЫВОЗ
               - КУРЬЕРСКАЯ ДОСТАВКА
               - ПОСТАМАТЫ
          x-enum-varnames:
               - PICKUP
               - COURIER_DELIVERY
               - PEDESTALS
        
      • Во втором случае будут созданы константы PICKUP, COURIER_DELIVERY, PEDESTALS с их указанными значениями в enum
    Описание

    Модуль для генерации API на основе OpenApi для Java

    Конвейеры
    0 успешных
    0 с ошибкой