tg

Новый проект

Для создания нового проекта необходимо выполнить команду:

> tg init someProject

Где someProject имя нового проекта.

В процессе создания будет создана базовая структура проекта, транспорт jsonRPC, а так же загружены зависимости.

Описание команды:

NAME: tg init - init project

USAGE: tg init go-msg-project

DESCRIPTION: init directory structures, basic configuration package

OPTIONS: --repo value base repository --jaeger use Jaeger tracer --zipkin use Zipkin tracer --mongo enable mongo support

Обновление проекта

В процессе внесения изменений в набор интерфейсов сервиса, перечень их методов, их сигнатур и/или используемых типов, необходимо актуализировать код транспорта и документацию.

Для это необходимо запустить следующую команду:

> tg transport --services ./pkg/someProject/service ---swagger

Описание команды:

NAME: tg transport - generate services transport layer

USAGE: tg transport --main --jaeger --swagger

OPTIONS: --services value path to services package --jaeger use Jaeger tracer --zipkin use Zipkin tracer (default) --mongo enable mongo support --swagger generate swagger docs

Документация (swagger)

Для документирования API сервиса, его методов и используемых типов данных, можно сгенерировать документацию в формате swagger.

Генерация swagger поддерживается для интерфейсов, предоставляющих API по jsonRPC и HTTP.

> tg swagger

Описание команды:

NAME: tg swagger - generate swagger documentation by interfaces

USAGE: tg swagger --iface FirstIface --iface SecondIface

OPTIONS: --services value path to services package --iface value interfaces included to swagger --json save swagger in JSON format

Аннотации

Для управления генератором и другими вспомогательными утилитами, используются аннотации. Аннотации могут иметь пакет, интерфейс и структуры.

Все аннотации, управляющие генератором tg, имеют префикс @tg.

Аннотации состоят из переменных. Переменные имеют имя, знак присваивания (=) и значение. Если указано только имя переменной, а знак присваивания и значение опущены, то считается, что переменная имеет значение равное True.

В одной строчке может быть несколько переменных, разделенных пробелами. Если значение переменной включает пробелы, то его нужно заключить в обратные кавычки «`».

Аннотации сервисов

Для корректной работы генератора swagger в одном из файлов в пакете service должны быть размещены следующие аннотации пакета:

title - имя сервиса в документации swagger version - версия документации swagger сервиса description - описание сервиса в документации swagger servers - список серверов, предоставляющих API сервиса typePrefix - префикс для типов, используемых в данном сервисе

Аннотации интерфейсов

Для управления генерацией кода и документации интерфейса могут применяться следующие аннотации:

http-server - генерация HTTP сервера, предоставляющего API интерфейса

jsonRPC-server - генерация jsonRPC сервера, предоставляющего API интерфейса

metrics - сбор метрик вызова методов интерфейса trace - трассировка вызова методов интерфейса log - логированное вызова методов интерфейса test - генерация тестов методом интерфейсов сервиса

disableExchange - запрет генерации типов для вызова методов интерфейса. Используется, если необходимо кастомизировать данные типы.

disableEndpoints - запрет генерации endpoint`ов. Используется, если необходимо кастомизировать данные типы.

typePrefix- префикс для типов, используемых в данном сервисе (имеет приоритет над аннотацией сервиса)

Аннотации методов

Для управления генерацией кода и документации методов интерфейса могут применяться следующие аннотации:

desc - описание метода в документации swagger. Поддерживает формат rich text. summary - описание метода в документации swagger http-encoder - имя метода для кодирования результата вызова метода, если требуется кастомизация

http-decoder - имя метода для декодирования параметров вызова метода, если требуется кастомизация

http-path - HTTP путь в URL, по которому будет доступен метод. В пути допускается указание параметров, например http-path=api/files/:fileId.

http-method - метод HTTP, который будет соотнесёт с вызовом метода

http-headers - список параметров метода, которые будут взяты из HTTP заголовков. Формат userID|x-user-id, где userID - имя параметра метода, x-user-id - имя заголовка. Может содержать список пар, разделённых запятыми.

http-arg - список параметров метода, которые будут взяты из аргументов URL. Формат `* profileID,count,maxID,sinceID`*. Разделитель запятая.

http-request-content-type - используется для указания списка типов передаваемого контента, отличного от * application/json* в документации swagger.

http-response-content-type - используется для указания списка типов возвращаемого контента, отличного от * application/json* в документации swagger. Разделитель вертикальная черта «|»

log-skip - пропуск полей при логировании, имена полей указываются через запятую «,»

disable-http - указание генератору пропустить создание HTTP реализации данного метода

disable-jsonRPC - указание генератору пропустить создание jsonRPC реализации данного метода

Аннотации типов

Для управления генерацией документации типов, используемых в методах интерфейсов могут применяться следующие аннотации:

type - переопределение типа в результирующем swagger example - пример значения. Может иметь как простой тип, так представлять собой json-объект.