Именно с этого начался мой проект.
До этого я никогда не писал спецификаций Swagger, и, несмотря на то, что я немного работал в этой отрасли, я лишь изредка взаимодействовал с живым сервером Swagger. Я был очень рад приступить к этой части проекта, потому что именно так я начал создавать архитектуру системы. Все началось с того, что я отправился на editor.swagger.io (предложение, которое было дано в описании проекта), получил базовую спецификацию swagger, которая была завершена, затем понял и отредактировал то, что там было. Мне потребовалось несколько часов, чтобы освоиться с ним, тыкая и тыкая в пример спецификации и пытаясь сделать из него то, что я хотел. Я очень рекомендую эту программу тем, кто только начинает писать спецификации Swagger. Просто получать мгновенную обратную связь о том, что я написал, было здорово, и это действительно помогло мне правильно сформулировать свои мысли с помощью инструмента.
Несмотря на это, моя первая спецификация была не самой лучшей, но она помогла получить архитектуру “на бумаге”.
Основным архитектурным решением, которое я сделал, было разделение действий на несколько конечных точек. Мне казалось, что я хочу, чтобы каждое действие было отделено друг от друга, и чтобы каждый контроллер мог сосредоточиться на проверке, которую он должен сделать, а не на том, чтобы выяснить, какая манипуляция выполняется, а затем сделать надлежащую проверку на входе манипуляции. На практике это привело к некоторому количеству повторяющегося кода, хотя это не повлияло на то, как быстро я смог завершить новую конечную точку, поскольку структура каждой конечной точки была одинаковой. Я также решил, что тип изображений, которые я буду поддерживать, будет только png и jpeg, поскольку я был уверен, что любая технология, которую я выберу для работы с изображениями, сможет работать с этими форматами.
Возвращаясь к документации swagger, я также попытался продумать возможные сообщения об ошибках, которые может иметь конечная точка, и начал их формулировать. Это было сделано потому, что одним из технических требований проекта было правильное использование HTTP-кодов для обозначения определенных ответов сервера. Мне очень хотелось убедиться, что я это сделал, и я думал об этом изначально, чтобы не забыть включить их, когда начну писать код. Этот документ был фактически моим дизайн-документом изначально, поэтому, когда я начинал кодировать, я довольно часто доставал его и ссылался на него.
Интересной частью первоначальной спецификации swagger было использование в ней слова “не реализовано”. Когда я писал спецификацию, я думал о том, что определенные HTTP-глаголы не используются, и я хотел явно указать это в моей swagger-спецификации. Каждая конечная точка имела кучу записей “не реализовано” для 5 других основных HTTP-глаголов, которые не использовались.
Это, конечно, попало в мой код, и мой API будет возвращать значение 501, если конечная точка и глагол не реализованы. Позже я узнал, что не было необходимости указывать, что HTTP-глагол не реализован. Все, чего не было в спецификации swagger, считалось нереализованным. Мои реализации только загромождали документацию. Как только документация swagger была завершена, я быстро создавал быстрый проект Node TypeScript, основанный на предыдущей работе с Node в паттерне MVC. Определяю несколько быстрых маршрутов и несколько пустых контроллеров и приступаю к работе.
В процессе работы над проектом я обнаружил, что мне очень хочется показать документацию swagger в Интернете. Честно говоря, это произошло после того, как я поработал и увидел, как другие инженеры демонстрируют свою документацию по swagger в Интернете. У меня было очень мало практического опыта работы непосредственно со Swagger, поэтому наблюдение за этим на работе очень вдохновило меня сделать то же самое в своей работе. Для этого я использовал пакет npm. Он запускал автоматически создаваемую HTML-страницу, которая показывала мою swagger-спецификацию и давала пользователю возможность совершать вызовы API с помощью CURL. Установка была не совсем тривиальной, поскольку мне нужно было решить две проблемы. Во-первых, моя спецификация swagger была выполнена в файле YAML, который обычно получается, если вы экспортируете свою спецификацию из editor.swagger.io (что я и сделал). Node не читает YAML нативно, поэтому мне пришлось получить другой пакет, чтобы позволить Node читать YAML-файл, который будет потребляться пакетом npm. Во-вторых, по умолчанию все вкладки для каждой конечной точки были открыты и заполняли веб-страницу. Хотя это и не мешало работе, но раздражало, поэтому я потратил немного времени, пытаясь найти правильную конфигурацию, чтобы все они закрывались. Это совсем не сложно, но я хотел бы отметить, что установка конфигурации в нужное место заняла больше времени, чем я хотел бы признать.
Вот ссылка на документацию по swagger: https://github.com/chadstewart/you-go-backend-project/blob/main/nodejs/api-docs/api-spec.yaml.
В следующей статье этой серии я расскажу об использовании TypeScript и о том, как это сделало работу над проектом приятной!