{"draftJsState":{"blocks":[{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":142,"offset":0,"style":"ITALIC"}],"text":"Это статья об основах программирования на Go. На канале я рассказываю об опыте перехода в IT с нуля, структурирую информацию и делюсь мнением.","type":"unstyled","key":"37kuk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":23,"offset":0,"style":"BOLD"}],"text":"Хой, джедаи и амазонки!","type":"unstyled","key":"88if1"},{"data":{},"depth":0,"entityRanges":[{"key":0,"length":27,"offset":96}],"inlineStyleRanges":[],"text":"Продолжаю осваивать новые навыки, необходимые для джуниор-разработчика. В предыдущей публикации улучшал навык с СУБД SQLite, сейчас хочу наработать навык с проектированием спецификаций по стандарту OpenAPI: однажды часть тестового задания была разработка сервиса по такой документации и требовалось сгенерировать свою. Спецификацию я тогда написал вручную и потратил на это несколько дней. ","type":"unstyled","key":"3a7qo"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Практиковать автоматизацию документирования API просто так не интересно - решил немного разобраться, как связаны бэкенд и фронтенд. Для этого напишу простой html-код и буду направлять его клиенту - браузеру; будет возможность на веб-странице нажимать на кнопки, создавая запросы для сервера. Намного интереснее тестировать и видеть свою работу, чем просто при работе с Postman без визуальной составляющей в браузере.","type":"unstyled","key":"84bks"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Когда вы прочитаете эту публикацию и повторите шаг за шагом каждое действие, вы разберётесь, как автоматически создавать спецификацию API такого типа:","type":"unstyled","key":"8rgrg"},{"data":{"image":{"id":"670f52fbf3594529c230ff22"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пример спецификации по стандарту OpenAPI с визуализацией","type":"atomic:image","key":"b4ahh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Публикация получилась длинная, вперёд - разбираться.","type":"unstyled","key":"f7omj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"1. Немного теории и рекламы","type":"header-two","key":"cap8k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Здесь хочу прорекламировать бесплатный курс на Stepik, на котором когда-то давно учился верстать страницы - \"Веб-разработка для начинающих: HTML и CSS\":","type":"unstyled","key":"cvt2q"},{"data":{"image":{"id":"6704d3ff8254d669e8b2c9b8"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Скриншот курса","type":"atomic:image","key":"8th4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На курсе мы поэтапно верстали аналог страницы о г.Хьюстон с Википедии.","type":"unstyled","key":"fvg18"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вам, конечно, необязательно проходить этот курс, чтобы попрактиковать фронтенд, для добавления к своему бэку визуальную часть. Я, чтобы не вспоминать все эти теги, заголовки и прочее из мира вёрстки сайтов, воспользовался услугами нейросети.","type":"unstyled","key":"acf9h"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"По поводу теории, просто напомню, что такое сваггер.","type":"unstyled","key":"b4qju"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":0,"style":"BOLD"}],"text":"Swagger - это инструментарий для разработки документации на API по стандарту OpenAPI. ","type":"unstyled","key":"fnibt"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":8,"offset":0,"style":"BOLD"}],"text":"OpenAPI - это правила оформления документа для документирования REST API, выполняется в форматах json или yaml. Такая спецификация позволяет разработчикам четко и последовательно определять структуру API, включая конечные точки, параметры, заголовки, ответы, ошибки и другие вещи.","type":"unstyled","key":"djcoq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пример текстового описания API по стандарту OpenAPI ниже:","type":"unstyled","key":"7s57h"},{"data":{"image":{"id":"670b5942831e6b4d70001dc8"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Описательная часть","type":"atomic:image","key":"2nkab"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Согласитесь, вручную писать такое - мягко говоря затруднительно.","type":"unstyled","key":"tuhp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Для меня, типичный сценарий, когда в реальной разработке нужна эта документация по стандарту OpenAPI, выглядит так:","type":"unstyled","key":"7965t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Команда разработчиков создаёт веб-сервис и фиксируют документально, какие эндпоинты будут доступны через API, как они организованы, какие запросы и ответы должен поддерживать сервис.","type":"blockquote","key":"cajd6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Например, будут эндпоинты: /users, /users/{id} /products/cheese и т.д. ","type":"blockquote","key":"b6ekk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Эндпоинт /users поддерживает запрос GET и ожидает ответ формата yaml с конкретными полями и должны быть предусмотрены определённые статусы ответа сервера; а эндпоинт /products/cheese поддерживает запрос POST и предусматривает передачу формата json со своими полями...","type":"blockquote","key":"7t25n"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Далее этой информацией будут руководствоваться в процессе разработки веб-сервиса новые программисты, QA-инженеры, сторонние разработчики, хотят интегрировать какое-то своё приложение в этот веб-сайт, или кто-нибудь ещё, глядя на относительно простую и понятную спецификацию API в графическом редакторе","type":"blockquote","key":"6o1rd"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пример визуализации спецификации по стандарту OpenAPI из шаблона Swagger Editor представлен ниже:","type":"unstyled","key":"68mhp"},{"data":{"image":{"id":"6705135b1fa4e5602c0e22bd"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Документация по стандарту OpenAPI в Swagger Editor https://editor.swagger.io/","type":"atomic:image","key":"eb4f1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Всю эту информацию можно получить и изучая код - но для этого нужно потратить несоразмерно больше времени и обладать способностью \"читать чужой код\". ","type":"unstyled","key":"426h3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В следующем параграфе мы разработаем приложение, и лишь после этого подготовим спецификацию по стандартам OpenAPI инструментарием Swagger.","type":"unstyled","key":"6nkha"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"2. Разрабатываем веб-сервис","type":"header-two","key":"atltj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"2.1. Структура сервиса","type":"header-three","key":"3pd8v"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Чтобы не переделывать или дорабатывать сервис, продумаю его архитектуру заранее. Какие у меня есть требования к сервису:","type":"unstyled","key":"9o1am"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Минимализм, чтобы не уходить в дебри в целях обучения;","type":"ordered-list-item","key":"6v5ac"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Наличие CRUD-операций (Create-Read-Update-Delete), чтобы попрактиковать написание спецификации по стандарту OpenAPI в разных вариантах;","type":"ordered-list-item","key":"2cdh0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Наличие фронтенда - простейшие html-документы, возможно даже без CSS;","type":"ordered-list-item","key":"64b97"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Наличие json'а в передаваемых клиентом и/или отправляемых сервером данных.","type":"ordered-list-item","key":"1a11m"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Без базы данных для минимализма кода сервиса. Хранить входящую информацию будем в файлах.","type":"ordered-list-item","key":"44i8k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Исходя из вышеизложенных требований, создал такую структуру:","type":"unstyled","key":"7ml0p"},{"data":{"image":{"id":"67051a2c551d0514026ef1c8"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Структура проекта","type":"atomic:image","key":"4ouuh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Я нарочно не стану менять скриншот, чтобы посмотреть - в процессе разработки такого простого сервиса, потребуется ли обновлять структуру, и если да - насколько значимы будут обновления.","type":"unstyled","key":"4vsj9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Кстати, в целях подготовки к работе с сервером через терминал, выполнил команды по созданию каталогов и файлов через CLI:","type":"unstyled","key":"1k498"},{"data":{"image":{"id":"67051ac4d526d47b71b72fee"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"3o0m5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":6,"offset":19,"style":"BOLD"},{"length":5,"offset":48,"style":"BOLD"},{"length":5,"offset":98,"style":"BOLD"}],"text":"Сперва создал файл go mod, затем одной командой mkdir создал три каталога, и далее одной командой touch создал несколько файлов.","type":"unstyled","key":"9rhvn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"2.2. HTML-файл","type":"header-three","key":"a6ldf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Чередой запросов-ответов, нейросеть подготовила для меня подходящую страничку .html. Откроем её в браузере без написания какого-либо бэкенда:","type":"unstyled","key":"59bue"},{"data":{"image":{"id":"67067f964ac7562f9eda5498"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Первая часть веб-страницы","type":"atomic:image","key":"2ivdu"},{"data":{"image":{"id":"67067fb9badccb6169793c6b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вторая часть веб страницы","type":"atomic:image","key":"a69v4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Интерфейс веб-страницы поделён на несколько блоков, указаны CRUD-операции.","type":"unstyled","key":"b16ig"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В html-файле есть три составляющие:","type":"unstyled","key":"178cg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сама html-разметка страницы;","type":"ordered-list-item","key":"54oua"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Стили элементов страницы;","type":"ordered-list-item","key":"75lbp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код на JavaScript.","type":"ordered-list-item","key":"5p3dj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Стили обычно пишут в отдельном CSS-файле, как и код на JavaScript - не встраивают в html-документ, а создают отдельный файл с расширением .js. Для наших целей удобнее поместить всё в один файл. Ниже примеры фрагментов каждой из трёх составляющих документа.","type":"unstyled","key":"3hfd2"},{"data":{"image":{"id":"670682269f99bb0f3f490b4d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разметка веб-страницы","type":"atomic:image","key":"dtlha"},{"data":{"image":{"id":"6706823dfe771c5939abcc56"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Стили веб-страницы","type":"atomic:image","key":"fr35"},{"data":{"image":{"id":"67068253303c8129cad9b364"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код на JavaScript веб-страницы начинается с тега script","type":"atomic:image","key":"acik8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Если со стилями и разметкой веб-страницы, я думаю, всё понятно, то что делает код JavaScript во фронтенде? В моём коде у него следующие функции:","type":"unstyled","key":"dkvaj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обрабатывает клики на кнопки: мы нажимаем не на текстовые ссылки, а на графические элементы;","type":"ordered-list-item","key":"ab3uu"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Формирует url-запроса для отправки на сервер;","type":"ordered-list-item","key":"arase"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Формирует json для тела запроса перед отправкой запроса на сервер;","type":"ordered-list-item","key":"alka5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обрабатывает ответ сервера: показывает уведомление о статусе операции или полученные данные.","type":"ordered-list-item","key":"57bau"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"При загрузке веб-страницы в браузере, код JavaScript выполняется уже на стороне клиента: в браузерах есть встроенные движки для обработки и выполнения JavaScript-кода, как и html и css-разметки.","type":"unstyled","key":"8k0ha"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"По п.2 из перечня выше: url-запросы содержат параметры для GET, PUT и PATCH методов согласно принципам REST. Для метода GET не принято передавать тела запроса, а какой именно товар нужно получить, передаётся в url в виде параметра ключ-значение либо расширением эндпоинта, например:","type":"unstyled","key":"cmdos"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":16,"offset":0,"style":"BOLD"}],"text":"/home/item/apple - расширение эндпоинта (используется в моём html-документе);","type":"unordered-list-item","key":"9m4vm"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"/home/item?product=apple - добавление параметра к запросу (product - поле json-структуры для общения клиент-сервер, описанной в html-документе).","type":"unordered-list-item","key":"8fbvn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Переходим к написанию бэкенда. ","type":"unstyled","key":"9v85k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"2.3. Основа backend'а","type":"header-three","key":"ctbun"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем минимальный необходимый код для отображения веб-страницы:","type":"unstyled","key":"6l6n7"},{"data":{"image":{"id":"670767a945d6d72caa8b8379"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Простой сервер","type":"atomic:image","key":"4rg6s"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Хорошо, сервер запустили, веб-страницу в браузере запустили командой","type":"unstyled","key":"1aob"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"http://localhost:8080/","type":"blockquote","key":"cmkjk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Кстати, если вы будете экспериментировать и веб-страница будет отображать не то, что ожидается, проблема может быть с КЭШем, для решения попробуйте:","type":"unstyled","key":"cvuav"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Запустите режим \"инкогнито\" в браузере сочетанием клавиш Ctrl+Shift+N и откройте веб-страницу там - посмотрите, что будет;","type":"ordered-list-item","key":"1nv7d"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Перезагрузите страницу вне режима \"инкогнито\" с очисткой КЭШа сочетанием клавиш Ctrl+Shift+R.","type":"ordered-list-item","key":"41lnc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"По части кода сервера хочу отдельно проговорить о функции Handle пакета http.","type":"unstyled","key":"dt681"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":11,"offset":11,"style":"BOLD"},{"length":10,"offset":122,"style":"BOLD"},{"length":4,"offset":148,"style":"BOLD"}],"text":"Обработчик http.Handle в строке 9 на иллюстрации будет отдавать контент, находящийся в каталоге templates за счёт функции FileServer того же пакета http при любом запросе из браузера (на соответствующий хост и порт). Сейчас функция отдаёт html-файл, который находится у меня в каталоге:","type":"unstyled","key":"ahfbm"},{"data":{"image":{"id":"67076acf5c5e4f1cf4cece8b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Содержимое каталога templates","type":"atomic:image","key":"2mdbg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вопрос: что отдаст сервер, если в этом каталоге несколько файлов? Например, мой hmtl файл и несколько иллюстраций или что-то ещё, например, текстовый файл? Вот примерно так:","type":"unstyled","key":"60an1"},{"data":{"image":{"id":"67076b4e8e955e7033705948"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавим пару файлов в каталог","type":"atomic:image","key":"dmget"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":10,"offset":84,"style":"BOLD"},{"length":4,"offset":102,"style":"BOLD"}],"text":"Ответ: по-прежнему веб-страницу. Почему? Переходим в документацию, читаем о функции FileServer пакета http:","type":"unstyled","key":"4ncmb"},{"data":{"image":{"id":"67076c1c9b265d7246d3f57c"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Документация Go на функцию FileServer","type":"atomic:image","key":"aii75"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Суть в чём - в первую очередь функция FileServer ищет в переданном в неё каталоге файл index.html, и отдаёт клиенту его. А вот если такой функции не находит, т.е. в каталоге будет например только два указанных выше файла:","type":"unstyled","key":"av666"},{"data":{"image":{"id":"67076ccf9b265d7246d4c8e7"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обновлённое содержимое каталога templates","type":"atomic:image","key":"a32q7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"То при загрузке веб-страницы командой localhost:8080, мы получим список файлов из каталога для выбора - что всё-таки хотим загрузить:","type":"unstyled","key":"slef"},{"data":{"image":{"id":"67076d151fa4e5602c2b8241"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Содержимое веб-страниц","type":"atomic:image","key":"anpe3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вернём файл index.html в каталог templates, удалим лишние файлы, и продолжим разработку веб-сервиса.","type":"unstyled","key":"8jv7i"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"2.4. Обработчик Create: POST-запросы","type":"header-three","key":"f19di"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Операция Create нужна для сохранения данных в хранилище по запросу клиента. Общаясь в соцсети при отправлении текстового сообщения или фотографии, заполняя ФИО в профиле и многое другое - это POST-запросы. Мы постоянно создаём новые данные, которые хранятся на серверах.","type":"unstyled","key":"68fcb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":31,"offset":0,"style":"BOLD"}],"text":"2.4.1. Алгоритм запроса клиента","type":"unstyled","key":"co2jn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем первый обработчик, который будет обрабатывать запросы клиента при нажатии кнопки \"Создать\":","type":"unstyled","key":"7r85u"},{"data":{"image":{"id":"67076de345d6d72caa929f1d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент веб-страницы","type":"atomic:image","key":"bpd56"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Как указано на иллюстрации, команда Create относится к POST-запросу согласно принципам REST и протоколу http. Происходить будет следующее:","type":"unstyled","key":"8na35"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пользователь вводит в браузер адрес сайта;","type":"ordered-list-item","key":"1v0bg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Браузер обращается к серверу по url и сервер отдаёт браузеру файл index.html с разметкой веб-страницей, стилями и кодом JavaScript;","type":"ordered-list-item","key":"9ifnb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пользователь смотрит на появившуюся в браузере веб-страницу, заполняет на веб-странице соответствующие поля и нажимает кнопку \"Создать\";","type":"ordered-list-item","key":"f2f8l"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":19,"offset":119,"style":"BOLD"},{"length":17,"offset":192,"style":"BOLD"}],"text":"Драйвер браузера обрабатывает код, написанный на JavaScript внутри файла index.html и отправляет серверу json с полями { product и price } с типами данных string и float соответственно по url /home/create_item. ","type":"ordered-list-item","key":"avrdf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На этом моменте нам нужен обработчик соответствующих событий. ","type":"unstyled","key":"89efc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":45,"offset":0,"style":"BOLD"}],"text":"2.4.2. Первая версия обработчика POST-запроса","type":"unstyled","key":"4l5gf"},{"data":{"image":{"id":"6707741a9b265d7246dde22d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код с обработчиком POST-запроса","type":"atomic:image","key":"8mtls"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализацию обработчика напишем в другом пакете - в файле /handlers/handlers.go. Но сперва напишем не обработчик, а сделаем внутри этого пакета ещё два файла:","type":"unstyled","key":"8occ5"},{"data":{"image":{"id":"670774b84ac7562f9e1e9796"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Содержимое каталога handlers через терминал","type":"atomic:image","key":"1c2rd"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В файле msg буду прописывать в константах код ошибок и информационных сообщений, которые будут повторяться в разных обработчиках. А в файле types пропишу структуру с полями json, которые передаёт фронтенд. Сейчас содержимое файлов выглядит так:","type":"unstyled","key":"d8in9"},{"data":{"image":{"id":"670775caa55a690072d763e7"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Константы сообщений","type":"atomic:image","key":"dgknf"},{"data":{"image":{"id":"670775e28a8ab555fe1fc1fb"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Структура в отдельном пакете","type":"atomic:image","key":"260un"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Переходим к реализации обработчика:","type":"unstyled","key":"doo85"},{"data":{"image":{"id":"67077621a55a690072d7cc36"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализация обработчика","type":"atomic:image","key":"9iska"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В строке 11 log.Printf... я пишу лог, который будет публиковать в терминал информацию о поступившем запросе с указанием с какого url пришёл запрос, протокол передачи данных и метод запроса. Константа msgNewRequest определена в другом файле этого же пакета, см. иллюстрацию выше.","type":"unstyled","key":"4r531"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В строке 13 мы создаём экземпляр структуры, сама структура описана в другом файле этого же пакета.","type":"unstyled","key":"pf4k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В случае неудачи декодирования переданного клиентом json'а, мы выводим сообщение об ошибке логом в терминал и отправляем клиенту статус ошибки. ","type":"unstyled","key":"4jkid"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"http.StatusBadRequest - это константа в виде числа. Хорошая практика прописывать статусы ответов не в виде чисел типа 404 или что-то ещё, а использовать константы, заботливо предоставленные разработчиками языка Go:","type":"unstyled","key":"7hq00"},{"data":{"image":{"id":"670777154dd2990e0cbd7b4d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Часть констант статусов ответа","type":"atomic:image","key":"56uig"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Ну и в конце я пока просто печатаю в терминал содержимое декодированного json-файла, чтобы посмотреть - то вообще пришло, или не то, что ожидалось.","type":"unstyled","key":"7r0us"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":59,"offset":0,"style":"BOLD"}],"text":"2.4.3. Тестирование первой версии обработчика POST-запросов","type":"unstyled","key":"5fa6t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Прототип обработчика POST-запросов написан, проверяем. Запускаем приложение в терминале:","type":"unstyled","key":"5t4bq"},{"data":{"image":{"id":"670777d917ebdf0fe151551a"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Запуск сервера","type":"atomic:image","key":"g4me"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Переходим в браузер, вводим информацию в поля раздела \"Создать товар\" и нажимаем кнопку \"Создать\". Появляется сообщение:","type":"unstyled","key":"b753a"},{"data":{"image":{"id":"6707779a396b9a1001712600"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Запрос и ответ на стороне клиента","type":"atomic:image","key":"hgj5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Переходим в терминал, смотрим что он пишет:","type":"unstyled","key":"bah8t"},{"data":{"image":{"id":"67077841f620057d910fbb7f"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Логи в терминале","type":"atomic:image","key":"eslnf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Отлично, информация от клиента получена и декодирована. ","type":"unstyled","key":"cdbop"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Доработаем обработчик: ","type":"unstyled","key":"8v1mq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавим функцию сохранения информации в файл (мы при определении архитектуры приложения решили, что не стоит перегружать учебный проект подключением БД, и ограничимся сохранением информации в файл). ","type":"unordered-list-item","key":"dnk3c"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавим проверку, что запрос с данного URL поступил с методом POST, а, например не GET, чтобы не делать лишнюю логику при ошибке.","type":"unordered-list-item","key":"fud7k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Изменим тип контента ответа: сейчас он был application/json, но я не возвращаю json-ов, а возвращают простой текст и то, если будет ошибка.","type":"unordered-list-item","key":"ds2ts"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":46,"offset":0,"style":"BOLD"}],"text":"2.4.4. Вторая версия обработчика POST-запросов","type":"unstyled","key":"aoadb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обновил код обработчика:","type":"unstyled","key":"5e66q"},{"data":{"image":{"id":"6708da8e03818b697329a236"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код обработчика","type":"atomic:image","key":"9dglj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Функция сохранения полученной от клиента информации в файл:","type":"unstyled","key":"f76cp"},{"data":{"image":{"id":"6707ea7e9613aa42c01fd77b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код сохранения файла","type":"atomic:image","key":"ep2cq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В коде сохранения мы делаем следующее:","type":"unstyled","key":"3305m"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":11,"offset":12,"style":"ITALIC"}],"text":"В строке 43 if ok = ... проверяем, все ли поля json-структуры заполнены: хотя это должно быть реализовано на стороне клиента в JavaScript, но мы фронтендерам доверять не станем и реализуем свои проверки. Детали реализации пока не важны, важно что либо все поля в json переданы и декодированы, либо нет.","type":"ordered-list-item","key":"abq4l"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Создаём каталог, если его нет, в котором будем хранить информацию.","type":"ordered-list-item","key":"du58l"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":65,"style":"ITALIC"}],"text":"Определяем имя файла по названию товара, переданного в json-поле procuct от клиента.","type":"ordered-list-item","key":"ev903"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Если файл с таким именем уже есть - возвращаем ошибку.","type":"ordered-list-item","key":"7tt7p"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Преобразуем цену товара в строку.","type":"ordered-list-item","key":"84f8g"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":5,"offset":96,"style":"ITALIC"}],"text":"Создаём файл с наименованием товара, а внутрь помещаем стоимость товара, переданную в json-поле price.","type":"ordered-list-item","key":"mks7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Печатаем лог об успешном завершении сохранения данных и возвращаем отсутствие ошибки.","type":"ordered-list-item","key":"7o1pf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В пакете я объявил константы, необходимые для функции сохранения:","type":"unstyled","key":"5rqj3"},{"data":{"image":{"id":"6707ecff6128b77fb3e3efd7"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Константы для работы с файлами и директорией","type":"atomic:image","key":"eddui"},{"data":{},"depth":0,"entityRanges":[{"key":1,"length":15,"offset":34}],"inlineStyleRanges":[],"text":"О константе perm и 0644 я писал в публикации #33. Права доступа к файлам и основы обработки ошибок.","type":"unstyled","key":"8e73b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Так выглядит функция проверки полей, декодированных в экземпляр структуры из json-объекта клиента:","type":"unstyled","key":"7e2eb"},{"data":{"image":{"id":"6707ec84072f907d53b0d787"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код проверки полей json-объекта","type":"atomic:image","key":"3upak"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Также я обновил содержимое файла msg, указав там новые сообщения в виде констант и доработал существующие константы:","type":"unstyled","key":"4cgtk"},{"data":{"image":{"id":"6707eccfb7308e79e9da1c34"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Константы сообщений","type":"atomic:image","key":"dl0h5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":56,"offset":0,"style":"BOLD"}],"text":"2.4.5. Создаём несколько записей в хранилище и тестируем","type":"unstyled","key":"ct9c8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Итак, обработчик доработан бизнес-логикой. Загрузим на сервер несколько товаров со стороны клиента:","type":"unstyled","key":"5baif"},{"data":{"image":{"id":"6707eeb3fde5aa1fe3f09b24"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пример добавления товара","type":"atomic:image","key":"dprcu"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Проверим через терминал содержимое каталога, куда сохраняем товары и цену на последний добавленный товар:","type":"unstyled","key":"5lk06"},{"data":{"image":{"id":"6707efba45d6d72caa6e2c42"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Команды в терминале","type":"atomic:image","key":"5hodg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Всё в порядке: в каталоге появляются файлы, в файлах - цена товара.","type":"unstyled","key":"1p182"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Кстати, фронтенд не позволяет отправить запрос без заполнения любого или обоих полей:","type":"unstyled","key":"5a5gs"},{"data":{"image":{"id":"6707f0c4996627484ce45233"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент веб-сайта","type":"atomic:image","key":"l3ec"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Но если бы фронтенд не предусматривал такой защиты от ошибок, мы реализовали этот код на стороне сервера: проверим его через postman, в который мы можем прописать свой json, чего не можем сделать через браузер:","type":"unstyled","key":"7muqo"},{"data":{"image":{"id":"6707f15e396b9a100130f7e2"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа с Postman","type":"atomic:image","key":"7tnq5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Как и ожидали - ответ с ошибкой 400 и сообщением в теле ответа об ошибке.","type":"unstyled","key":"4e88l"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"То же самое можем получить, если в одном терминале запустим сервер, а в другом создадим запрос через утилиту curl, ниже на иллюстрации представлены два терминала - хотя зрительно видимость одного:","type":"unstyled","key":"1o96b"},{"data":{"image":{"id":"6707f2ea8a8ab555fefd90a7"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Тестируем сервер в терминале","type":"atomic:image","key":"dtvn8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Проверим ещё в Postman'e, что будет, если сделаем не POST-операцию, а какую-нибудь другую:","type":"unstyled","key":"c4tib"},{"data":{"image":{"id":"6708db7c6128b77fb3c0c09f"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в Postman","type":"atomic:image","key":"3lqc0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Как и ожидалось - в теле ответа информационное сообщение, и код статуса ответа 405 \"Method Not Allowed\".","type":"unstyled","key":"ehg10"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Посмотрим, что пишет терминал: ","type":"unstyled","key":"aalqr"},{"data":{"image":{"id":"6708dbbebadccb616981305a"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"eojb3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Терминал соответственно тоже выдаёт лог ошибки.","type":"unstyled","key":"8lcsd"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":45,"offset":0,"style":"BOLD"}],"text":"2.4.6. Третья версия обработчика POST-запроса","type":"unstyled","key":"dkf0e"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":5,"offset":133,"style":"BOLD"},{"length":3,"offset":143,"style":"BOLD"}],"text":"Пока я писал этот пост, лучше разобрался с архитектурой REST. И вот что выяснил: для POST-запросов необходимо возвращать код статуса 201, а не 200 и информацию о созданном контенте. Пусть это будет имя созданного файла. Доработаем реализацию обработчика:","type":"unstyled","key":"53kl0"},{"data":{"image":{"id":"670a2092bea06939b62ece70"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код обработчика","type":"atomic:image","key":"bp7c3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Доработаем функцию сохранения - теперь она возвращает имя файла по относительному пути:","type":"unstyled","key":"cqq8a"},{"data":{"image":{"id":"670a20bc9f99bb0f3fc5c794"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сохранение файла","type":"atomic:image","key":"7ulch"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"При работе из браузера, визуально ничего не изменится. Протестируем обработчик через Postman:","type":"unstyled","key":"53nb4"},{"data":{"image":{"id":"670a20e7bef9486c080b569d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в Postman","type":"atomic:image","key":"8cho1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В теле ответа появилась информация о созданном ресурсе. Думаю, можно считать этот обработчик, спроектированным по принципам REST.","type":"unstyled","key":"1pejq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Итак, первый эндпоинт обработали. Остаётся ещё 4.","type":"unstyled","key":"aab4i"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":13,"offset":24,"style":"BOLD"}],"text":"2.5. Обработчик Update: PATCH-запросы","type":"header-three","key":"42dr1"},{"data":{},"depth":0,"entityRanges":[{"key":2,"length":6,"offset":68}],"inlineStyleRanges":[],"text":"Изменяя отправленное сообщение в соцсети, редактируя свой профиль в Тенчат (отечественный аналог LinkedIn), изменяя язык или настройки уведомления на веб-странице, редактируя пост в блоге, изменяя пароль или адрес доставки в интернет-магазине - мы создаём PATCH-запросы: изменяем ранее созданные данные.","type":"unstyled","key":"fse1g"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Patch можно перевести с английского, как \"заплатка\". Это своего-рода доработка ранее пошитой одежды.","type":"blockquote","key":"15pnb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"2.5.1. Данные от клиента","type":"unstyled","key":"ccuo6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разберём, что отдаёт нам клиент при Patch-запросе.","type":"unstyled","key":"972n9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Клиент отдаёт URL вида: /home/update_item/<ТекущееНазваниеТовара>","type":"unordered-list-item","key":"87am2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Json-объект вида: { \"price\": 190.60 }","type":"unordered-list-item","key":"6moh3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Таким образом, нам нужно расшифровать конечную часть энпоинта в наименование текущего товара, найти файл с таким именем и перезаписать содержимое файла обновлённой ценой.","type":"unstyled","key":"4b1r"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":4,"offset":58,"style":"BOLD"},{"length":15,"offset":198,"style":"BOLD"}],"text":"В случае успеха обновления будем возвращать статус ответа 204 - работу выполнили, но тела ответа не направляем. Статус 204 (как и все остальные коды статусов) определён константой в пакете http как StatusNoContent.","type":"unstyled","key":"8ckgi"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":34,"offset":0,"style":"BOLD"}],"text":"2.5.2. Первая версия PATCH-запроса","type":"unstyled","key":"eoekc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавляем обработчик обновлений товара в функцию main пакета main:","type":"unstyled","key":"dfq2f"},{"data":{"image":{"id":"6708c71f551d051402e9c7de"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обработчик PATCH-запроса","type":"atomic:image","key":"hbms"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пишем реализацию обработчика:","type":"unstyled","key":"crgqs"},{"data":{"image":{"id":"6708d889bef9486c08b0de7f"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализация обработчика","type":"atomic:image","key":"fk297"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вообще, декодирование джейсона и создание экземпляра структуры - такое полезнее делать на отдельном слое (в другом пакете, предназначенном для соответствующих задач). С опытом это будет уже автоматически делаться, а сейчас напишем как пишется, а далее, если будет желание - отрефакторим.","type":"unstyled","key":"c7jpu"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В функции должно быть всё понятно - делаем примерно то же самое, что при реализации обработчика сохранения файлов.","type":"unstyled","key":"acs5k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Затем реализуем функцию обновления данных:","type":"unstyled","key":"fg6r0"},{"data":{"image":{"id":"6708d30cb3c77444905a6cf1"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код обновления данных","type":"atomic:image","key":"c8q7j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В строке 96 получаем из url название товара.","type":"unstyled","key":"860lj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В строке 98 присваиваю полю Product экземпляра структуры значение товара, т.к. в текущем экземпляре структуры это поле отсутствует - клиент передал json-объект с полем. А я хочу воспользоваться функцией по проверке корректности декодированных в экземпляр структуру полей и не создавать новую функцию: существующая функция, созданная ранее, проверяет оба поля и выдаст ошибку, если не найдёт поля Product.","type":"unstyled","key":"5haj6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В строке 107 перезаписываю файл новым содержимым. ","type":"unstyled","key":"aukju"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Ещё я решил вывести в отдельную функцию процесс преобразования типа float64 в строку текста:","type":"unstyled","key":"1t64j"},{"data":{"image":{"id":"6708d60e17ebdf0fe1163c69"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Преобразование типов","type":"atomic:image","key":"7esc6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В остальном код похож на сохранение файла в POST-запросе. Переходим к проверке.","type":"unstyled","key":"9dj1k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":50,"offset":0,"style":"BOLD"}],"text":"2.5.3. Проверяем работу обработчика PATCH-запросов","type":"unstyled","key":"9495q"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Заполняем поля на веб-странице:","type":"unstyled","key":"6e94o"},{"data":{"image":{"id":"6708d69b303c8129cad1c69c"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в браузере","type":"atomic:image","key":"7uml2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Смотрим, что пишет терминал сервера:","type":"unstyled","key":"bar09"},{"data":{"image":{"id":"6708d6ed9f99bb0f3f42d4a2"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"1gpc4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Так, мы видим что получен запрос и напечатан товар, расшифрованный из эндпоинта. Мы забыли добавить лог успешного обновления. Это мы сделаем, а сейчас проверим что там в содержится в файле \"Дыня.txt\":","type":"unstyled","key":"7vr9g"},{"data":{"image":{"id":"6708d92503818b6973276769"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"1mcm5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Так, у нас нет информации - что было в файле до обновления. Обновим в браузере данные вновь и посмотрим на содержимое файла:","type":"unstyled","key":"c01u9"},{"data":{"image":{"id":"6708d989b4c8467ea8b97b0b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обновление товара Дыня в браузере","type":"atomic:image","key":"10cmr"},{"data":{"image":{"id":"6708d9a6831e6b4d70861e67"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Смотрим в терминале","type":"atomic:image","key":"d4cmf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Итак, данные вновь обновлены. Мы молодцы. Переходим к следующему запросу.","type":"unstyled","key":"7mq8g"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":30,"offset":5,"style":"BOLD"}],"text":"2.6. Обработчик Update: PUT-запросы","type":"header-three","key":"ddql0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"PUT-запросы похожи на PATCH, но обновляют все данные, а не часть. Честно говоря, я не разобрался, когда нужны PUT, а когда PATCH-запросы: PUT в моём понимании менее применим. А так его цель та же - обновить ранее созданные данные, но если PATCH обновлял часть данных, то PUT перезаписывает все данные.","type":"unstyled","key":"950v5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"2.6.1. Данные от клиента","type":"unstyled","key":"d4570"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На веб-странице мы обновляем все данные о товаре:","type":"unstyled","key":"6rf69"},{"data":{"image":{"id":"6708e79da56c23458f90b293"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент веб-страницы для PUT-запроса","type":"atomic:image","key":"4v2ic"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разберём, что отдаёт нам клиент при PUT-запросе.","type":"unstyled","key":"9erl3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Клиент отдаёт URL вида: /home/update_item/<ТекущееНазваниеТовара>","type":"unordered-list-item","key":"1sla4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Json-объект вида: {\"product\": \"НовыйТовар\", \"price\": 200.50 }","type":"unordered-list-item","key":"4a146"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Как и для PATCH-запроса, нам нужно расшифровать конечную часть энпоинта в наименование текущего товара, найти файл с таким именем и перезаписать содержимое файла обновлённой ценой и наименование файла с новым товаром.","type":"unstyled","key":"2njn2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":4,"offset":73,"style":"BOLD"}],"text":"В случае успеха обновления будем возвращать статус ответа будет таким же 204 - работу выполнили без создания нового ресурса, и тела ответа не направляем. ","type":"unstyled","key":"22o48"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вот что ещё я обнаружил - что клиент отправляет нам по одному url запросы типа PATCH и PUT: /home/update_item/<ТекущееНазваниеТовара>","type":"unstyled","key":"3gjrs"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Если мы не хотим использовать сторонние библиотеки, где при объявлении обработчиков можно сразу указать метод, то нам потребуется сделать отдельную функцию.","type":"unstyled","key":"2lpk0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":45,"offset":0,"style":"BOLD"}],"text":"2.6.2. Первая версия обработчика PUT-запросов","type":"unstyled","key":"3ge0j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Функцию main пакета main не будем обновлять: у нас по одному эндпоинту будут обслуживаться два типа запросов: PUT и PATCH.","type":"unstyled","key":"4f8oj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Создадим новую функцию, которая будет смотреть, какой метод пришёл с /home/update_item/<ТекущееНазваниеТовара>, доработаем реализацию обработчика PATCH и напишем реализацию обработчика PUT.","type":"unstyled","key":"7rr8t"},{"data":{"image":{"id":"6709115b17ebdf0fe17f0b4c"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код обработчика единого эндпоинта для нескольких методов","type":"atomic:image","key":"fqd23"},{"data":{"image":{"id":"670911a1d526d47b71475d06"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Обновлённый код реализации обработчика PATCH-запросов","type":"atomic:image","key":"dvnd4"},{"data":{"image":{"id":"670911c1bef9486c0809a680"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализация обработчика PUT-запросов","type":"atomic:image","key":"ai800"},{"data":{"image":{"id":"670911e14b1389626e6a7dbd"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Логика реализации PUT-запроса","type":"atomic:image","key":"fa5ar"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код написан, добавлены несколько констант с сообщениями об ошибок, которые я приводить здесь не буду, т.к. их содержимое не принципиально и интуитивно понятно. Тестируем сервис.","type":"unstyled","key":"c19f8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":28,"offset":0,"style":"BOLD"}],"text":"2.6.3. Тестируем PUT-запросы","type":"unstyled","key":"6p1r1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Заполняем соответствующие поля на веб-сайте:","type":"unstyled","key":"4597q"},{"data":{"image":{"id":"6709126292eb807fc970fcad"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в браузере","type":"atomic:image","key":"f7752"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Проверяем, что в терминале:","type":"unstyled","key":"62j9d"},{"data":{"image":{"id":"6709128dbadccb6169dfe23c"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"eoviq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сервис отработал корректно: заменил имевшийся файл Дыня со своим содержимым на товар Арбуз с новым содержимым. Проверим содержимое каталога и файла:","type":"unstyled","key":"dlv9p"},{"data":{"image":{"id":"670912e13f6abd2101db1c65"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"6ptfp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Всё на своих местах. Переходим к следующему типу запроса.","type":"unstyled","key":"5dksk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":26,"offset":5,"style":"BOLD"}],"text":"2.7. Обработчик DELETE-запросов","type":"header-three","key":"89a2k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"DELETE-запросы удаляют ресурсы: ненужные записи в мессенджере или блоге, фотографии, контакты в телефонной книжке (в т.ч. из облачного хранилища) и т.д.","type":"unstyled","key":"dm9op"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"2.7.1. Данные от клиента","type":"unstyled","key":"959cl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На веб-странице мы обновляем все данные о товаре:","type":"unstyled","key":"9jqq0"},{"data":{"image":{"id":"6709134972a5820eb3f12d3e"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент веб-сайта","type":"atomic:image","key":"12kse"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разберём, что отдаёт нам клиент при DELETE-запросе.","type":"unstyled","key":"vvfi"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"URL вида: /home/delete_item/<НазваниеТовара>","type":"unordered-list-item","key":"33o9s"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":4,"offset":87,"style":"BOLD"}],"text":"В случае успеха удаления будем возвращать статус ответа таким же, как при PUT и PATCH: 204 - работу выполнили, и тело ответа не направляем. ","type":"unstyled","key":"9dd88"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":3,"offset":55,"style":"BOLD"}],"text":"Если товар не будет найден, вернём клиенту код статуса 404 - ресурс не найден.","type":"unstyled","key":"2gdpn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В случае других ошибок будем возвращать статусы кодов:","type":"unstyled","key":"la8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Передан не DELETE-запрос: код 405 - статус не разрешён;","type":"unordered-list-item","key":"e9qjk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Не смогли выполнить запрос: код 500 - внутренняя ошибка сервера.","type":"unordered-list-item","key":"7l3h4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":47,"offset":0,"style":"BOLD"}],"text":"2.7.2. Первая версия обработчика DELETE-запроса","type":"unstyled","key":"1i1rj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавим обработчик в функцию main пакета main:","type":"unstyled","key":"79gnp"},{"data":{"image":{"id":"6709157803818b69738f7be5"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Создаём обработчик DELETE-запроса","type":"atomic:image","key":"7747k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализуем обработчик:","type":"unstyled","key":"esfm"},{"data":{"image":{"id":"670a115440073173e4a8c762"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализация обработчика DELETE-запросов","type":"atomic:image","key":"6fjqk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Особенность этой реализации в том, что из функции, отвечающей за бизнес-логику я возвращаю ошибку и статус: если сервер \"пятисотит\" - это один ответ клиенту, а если товар не найден - т.е. код статуса 404, то ответ клиенту другой. В остальном логика та же, как в предыдущих запросах.","type":"unstyled","key":"enaao"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализация функции удаления товара:","type":"unstyled","key":"3ab82"},{"data":{"image":{"id":"67091c0c9f99bb0f3fb96e1c"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код удаления товара","type":"atomic:image","key":"4vmu3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код написан, тестируем.","type":"unstyled","key":"frba7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":30,"offset":0,"style":"BOLD"}],"text":"2.7.3. Реализуем DELETE-запрос","type":"unstyled","key":"cpr3b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Заполняем поле на веб-сайте:","type":"unstyled","key":"3luhq"},{"data":{"image":{"id":"67091c5d45d6d72caad0023b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в браузере","type":"atomic:image","key":"9k2cb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Смотрим, что пишет терминал:","type":"unstyled","key":"36ql9"},{"data":{"image":{"id":"67091c9672a5820eb30144ba"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"16uan"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Я использовал раздельный терминал: верхняя часть - работа сервера, нижняя часть - вспомогательный терминал, посмотрел содержимое каталога где хранятся данные о товарах: видно, что товар удалён.","type":"unstyled","key":"1cni8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Попробуем вновь удалить этот же товар:","type":"unstyled","key":"bqj9e"},{"data":{"image":{"id":"670a1091303c8129ca445acb"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Повторное удаление товара","type":"atomic:image","key":"3obv4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Ответ сервера браузеру: нечего удалять. Смотрим, что пишет терминал:","type":"unstyled","key":"2kd27"},{"data":{"image":{"id":"670a1124072f907d5326fee6"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"7j2gn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Всё как и ожидалось: код работает. Переходим к следующему запросу.","type":"unstyled","key":"f26vn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":23,"offset":5,"style":"BOLD"}],"text":"2.8. Обработчик GET-запросов","type":"header-three","key":"en0l1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"GET-запросы запрашивают информацию: загрузка и просмотр веб-страницы, поисковой запрос, просмотр изображения из миниатюры и т.д.","type":"unstyled","key":"5ibrj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"2.8.1. Данные от клиента","type":"unstyled","key":"enh0p"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На веб-странице мы ищем данные о конкретном товаре:","type":"unstyled","key":"dlk9j"},{"data":{"image":{"id":"670a125bbadccb6169ed9d10"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент веб-сайта ","type":"atomic:image","key":"15cp9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разберём, что отдаёт нам клиент при GET-запросе.","type":"unstyled","key":"eav19"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"URL вида: /home/item/<НазваниеТовара>","type":"unordered-list-item","key":"2bsa7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":3,"offset":69,"style":"BOLD"}],"text":"В случае успеха получения информации, будем возвращать статус ответа 200 и json с информацией о товаре.","type":"unstyled","key":"8pol7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":3,"offset":55,"style":"BOLD"}],"text":"Если товар не будет найден, вернём клиенту код статуса 404 - ресурс не найден.","type":"unstyled","key":"56rst"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В случае других ошибок будем возвращать статусы кодов:","type":"unstyled","key":"86dqi"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":3,"offset":27,"style":"BOLD"}],"text":"Передан не GET-запрос: код 405 - статус не разрешён;","type":"unordered-list-item","key":"5lk7j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":3,"offset":32,"style":"BOLD"}],"text":"Не смогли выполнить запрос: код 500 - внутренняя ошибка сервера.","type":"unordered-list-item","key":"e35si"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":29,"offset":0,"style":"BOLD"}],"text":"2.8.2. Обработчик GET-запроса","type":"unstyled","key":"99lrq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Дополним функцию main пакета main:","type":"unstyled","key":"2m80m"},{"data":{"image":{"id":"670a134803818b69739969ae"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавили обработчик GET-запросов","type":"atomic:image","key":"7c6in"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем реализацию обработчика GET-запросов:","type":"unstyled","key":"972v9"},{"data":{"image":{"id":"670a19ae996627484c5afdb3"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Реализация обработчика GET-запросов","type":"atomic:image","key":"eet0b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В коде мы делаем следующее:","type":"unstyled","key":"fv970"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Печатаем лог в терминал с информацией о полученном запросе;","type":"ordered-list-item","key":"30lg9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Проверяем корректность метода запроса;","type":"ordered-list-item","key":"5ur3f"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вызываем функцию, возвращающую нужный для отправки клиенту json-объект, статус ответа ошибки если имеется и ошибку;","type":"ordered-list-item","key":"ajtv2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Две проверки на коды статусов, если есть ошибки;","type":"ordered-list-item","key":"8q8fu"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Отправка кода статусу и json-объект клиенту.","type":"ordered-list-item","key":"5a921"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем функцию для подготовки json-объекта для отправки клиенту:","type":"unstyled","key":"4uls5"},{"data":{"image":{"id":"670a1a78996627484c5be338"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код подготовки ответа","type":"atomic:image","key":"8mqoe"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В коде выполняется следующее:","type":"unstyled","key":"3an2p"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Извлекаем из ULR наименование необходимого товара;","type":"ordered-list-item","key":"7t0mb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Формируем имя файла для поиска товара;","type":"ordered-list-item","key":"9sl2t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Выполняем проверку, есть ли такой файл;","type":"ordered-list-item","key":"52a0b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вызываем функцию, возвращающую цену товара с типом данных float64 и ошибку;","type":"ordered-list-item","key":"ba7pr"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Выполняем проверку, удалось ли получить цену товара;","type":"ordered-list-item","key":"14nnv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Создаём экземпляр структуры и кладём в неё имя требуемого товара и его цену;","type":"ordered-list-item","key":"8lqgn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Формируем json-объект из созданного экземпляра структуры;","type":"ordered-list-item","key":"aqg7b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Выполняем проверку успешности создания json-объекта;","type":"ordered-list-item","key":"fv07g"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Печатаем лог в терминал об успешном создании json-объекта;","type":"ordered-list-item","key":"1kakn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Возвращаем json-объект.","type":"ordered-list-item","key":"1abv9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем функцию чтения файла. Она читает файл и преобразует тип string в тип float64 - хотя считается для чистого кода, каждая функция должна делать что-то одно для гибкости кода, я считаю что эта функция лаконична и гибка:","type":"unstyled","key":"8q2so"},{"data":{"image":{"id":"670a1cbfded294460255b426"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код получения цены ","type":"atomic:image","key":"8tb6b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"К слову, название функции readFile не совсем отражает её действие - думаю, логичнее назвать её price или как-то в этом духе. ","type":"unstyled","key":"fftds"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Итак, код написан, проверяем.","type":"unstyled","key":"6q3p9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":39,"offset":0,"style":"BOLD"}],"text":"2.8.3. Тестируем обработчик GET-запроса","type":"unstyled","key":"1a39k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Заполняем требуемое поле в браузере:","type":"unstyled","key":"a5d5u"},{"data":{"image":{"id":"670a1d6f3a7a5a4b267a9343"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Веб-страница","type":"atomic:image","key":"3v7sm"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сразу получаем уведомление с json-объектом. Смотрим, что происходит в терминале:","type":"unstyled","key":"3cdn0"},{"data":{"image":{"id":"670a1dc8551d0514028f0219"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"9mh1m"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В верхней части - терминал сервера, в нижней части - вспомогательный терминал, который показывает какие файлы в хранилище и содержимое файла запрошенного товара. Всё сходится.","type":"unstyled","key":"bcqug"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На этом этапе можно заканчивать разработку сервиса и переходить к Swagger'у. ","type":"unstyled","key":"165pr"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3. Инструментарий Swagger","type":"header-two","key":"c7ehh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Основная идея автоматической генерации спецификации API по стандарту OpenAPI, следующая:","type":"unstyled","key":"3pni9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В коде пишем особые комментарии об API - своего рода, высокоуровневый код;","type":"ordered-list-item","key":"89ile"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Устанавливаем утилиту для генерации спецификации API;","type":"ordered-list-item","key":"fr2ji"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Запускаем утилиту и она генерирует спецификацию, преобразуя высокоуровневые комментарии в более низкоуровневые.","type":"ordered-list-item","key":"dfgv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Далее эту спецификацию можем использовать для визуализации API - скриншоты в начале публикации.","type":"unstyled","key":"1dks0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.1. Общая информация","type":"header-three","key":"9064h"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Я нашёл несколько библиотек для автоматической генерации спецификации API по стандарту OpenAPI:","type":"unstyled","key":"9d8t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swaggo;","type":"unordered-list-item","key":"fk3h8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"go-swagge;","type":"unordered-list-item","key":"2h5eg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"gofiber;","type":"unordered-list-item","key":"e77qh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"oapi-codegen;","type":"unordered-list-item","key":"6iqk8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"ogen-go.","type":"unordered-list-item","key":"345br"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разбираться будем с первой - Swaggo. Установим его, ниже скриншот из официальной документации на GitHub:","type":"unstyled","key":"c0g0a"},{"data":{"image":{"id":"670a4b738c2bc40f578597d3"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Установка библиотеки Swaggo","type":"atomic:image","key":"e418r"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Далее нужно каким-то образом сообразить, как дополнить комментариями наш код, чтобы Swaggo считал информацию и преобразовал в спецификацию API по стандарту OpenAPI. Ниже фрагмент информации по комментированию кода из ReadME библиотеки Swaggo:","type":"unstyled","key":"e5b0g"},{"data":{"image":{"id":"670a4bd2b7308e79e93d50c4"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Таблица комментирования ","type":"atomic:image","key":"7bjvf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Также имеется выбор библиотек по обработке http-запросов, поддерживаемых библиотекой Swaggo - здесь есть и стандартная библиотека net/http:","type":"unstyled","key":"b2mfo"},{"data":{"image":{"id":"670a4c6503818b6973de217b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Перечень поддерживаемых фреймворков","type":"atomic:image","key":"k3kv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Суть в чём - нужно добавить комментарии согласно требованиям библиотеки Swaggo. Напишем минимальное количество комментариев для одного обработчика, чтобы протестировать как всё работает.","type":"unstyled","key":"628n2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.2. Документация на обработчик POST-запроса","type":"header-three","key":"864jj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swagger-аннотирование делится на два этапа: общее описание проекта, которое выполняем в пакете main перед функцией main, и аннотации для каждого обработчика.","type":"unstyled","key":"6rkge"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":42,"offset":0,"style":"BOLD"}],"text":"3.2.1. Минимальная спецификация по OpenAPI","type":"unstyled","key":"a96i7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сделаю самый простой проект, чтобы опробовать технологию автогенерации.","type":"unstyled","key":"6nbbu"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Заполню общее описание в функции main комментариями title, version, description, contact name-url-evail, host и basePath - которые интуитивно понятны:","type":"unstyled","key":"cbn9l"},{"data":{"image":{"id":"670b555566c7c46b64b33110"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Общее описание проекта перед функцией main","type":"atomic:image","key":"b73na"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":9,"offset":72,"style":"BOLD"}],"text":"Описание получилось какое-то неотформатированное. Воспользуюсь командой swag fmt в терминале, результат:","type":"unstyled","key":"49grh"},{"data":{"image":{"id":"670b561eb3c7744490392034"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Отформатированное swagger-описание проекта","type":"atomic:image","key":"2ij6v"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Создал описание обработчика перед функцией-реализацией обработчика POST-запроса:","type":"unstyled","key":"6macb"},{"data":{"image":{"id":"670b5774353dbb6d0f91d516"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swagger-описание обработчика","type":"atomic:image","key":"612g9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Посмотрим разъяснения по полям Accept, Produce и Param в ReadME библиотеки Swaggo - остальные поля, думаю, интуитивно понятны.","type":"unstyled","key":"4e9r5"},{"data":{"image":{"id":"670b5fa2a56c23458ffa3f51"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Описание аннотаций Swagger","type":"atomic:image","key":"fjj9r"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В документация есть ссылка на Mime Types.","type":"unstyled","key":"213dh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"MIME (Multipurpose Internet Mail Extensions) types — это стандартизированные идентификаторы, которые используются для указания типа содержимого, передаваемого через интернет. Изначально разработанные для электронной почты, сейчас MIME-типы широко применяются в HTTP-протоколе для указания типа файлов, передаваемых между клиентом и сервером.","type":"blockquote","key":"5omn0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Посмотрим, что в ReadME библиотеки Swaggo говорится о Mime Types:","type":"unstyled","key":"an0q3"},{"data":{"image":{"id":"670b5d1b303c8129ca9b8a33"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент ReadMe библиотеки Swaggo о Mime Types","type":"atomic:image","key":"ajhl7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":37,"style":"BOLD"}],"text":"В общем, по-русски говоря, аннотация @Accept говорит о том, какие данные в теле запроса ожидаются от клиента. В моём случае API ожидает от клиента в теле запроса json-объект.","type":"unstyled","key":"fgpb4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":8,"offset":10,"style":"BOLD"}],"text":"Аннотация @Produce говорит о том, какой объект в теле ответа сервер возвращает клиенту: в данном случае также json-объект.","type":"unstyled","key":"6s5ed"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":6,"offset":10,"style":"BOLD"}],"text":"Аннотация @Param используется для определения параметра, который передаются в API-метод. Её расшифровка посложнее двух предыдущих аннотаций. Взглянем ещё раз на аннотацию:","type":"unstyled","key":"27nfi"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Param item body Item true \"Создаем новый товар\"","type":"blockquote","key":"4to9f"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"или её можно представить так:","type":"unstyled","key":"30j7o"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Param \"\"","type":"blockquote","key":"98fa5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разберем теги аннотации Param подробнее:","type":"unstyled","key":"c87f5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":4,"offset":7,"style":"BOLD"},{"length":4,"offset":133,"style":"ITALIC"},{"length":4,"offset":151,"style":"ITALIC"}],"text":"1. Тег name - это просто название, чтобы по-названию объяснить структуру данных, которая ожидается из запроса. В нашем случае у тега name наименование item.","type":"unstyled","key":"5q3fs"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":10,"offset":7,"style":"BOLD"}],"text":"2. Тег param type указывает, где в запросе находится параметр, в нашем случае - в body. В ReadMe библиотеки Swaggo указаны следующие типы:","type":"unstyled","key":"f46ai"},{"data":{"image":{"id":"670b6e7803818b6973fd9dda"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разновидности Param type библиотеки Swaggo","type":"atomic:image","key":"6l7hm"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":10,"offset":7,"style":"BOLD"},{"length":4,"offset":57,"style":"BOLD"}],"text":"3. Тег data type определяет тип данных для объекта тега . В нашем случае тип данных Item - это наша пользовательская структура, описанная в коде, см. параграф 2.4.2 публикации. Посмотрим, что написано о типах данных в Readme библиотеки Swaggo:","type":"unstyled","key":"87pa5"},{"data":{"image":{"id":"670b702eb4c8467ea8a7e7d0"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент ReadMe библиотеки Swaggo","type":"atomic:image","key":"ftkm7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В общем, аннотация @Param через тег подтягивает структуру Item в спецификацию.","type":"unstyled","key":"6duo1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":15,"offset":6,"style":"BOLD"},{"length":2,"offset":31,"style":"BOLD"},{"length":4,"offset":107,"style":"ITALIC"}],"text":"4. Тег is mandatory? определяет, требуется ли этот параметр для выполнения запроса (в нашем случае указано true, - требуется). Пока не могу представить примеров, где этот параметр будет false.","type":"unstyled","key":"d47m0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":7,"style":"BOLD"}],"text":"5. Тег comment задаёт описание параметра, чтобы читающие спецификацию специалисты понимали, что должно быть передано в этом параметре.","type":"unstyled","key":"147fg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":52,"offset":14,"style":"ITALIC"}],"text":"Теперь строка // @Param item body Item true \"Создаем новый товар\" не должна вызывать вопросов. ","type":"unstyled","key":"ecvqa"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":32,"style":"BOLD"}],"text":"Ещё хочу сказать про аннотацию @Success - документирует, какой должен быть ответ при успешном выполнении запроса. Взглянем на описание аннотации в ReadMe библиотеки Swaggo:","type":"unstyled","key":"rsi5"},{"data":{"image":{"id":"670cc97c45827d77e89cd533"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент ReadMe библиотеки Swaggo","type":"atomic:image","key":"fv2s7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В целом, всё знакомые теги.","type":"unstyled","key":"9oecd"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напомню, как выглядит аннотация в нашем коде:","type":"unstyled","key":"caloh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Success 201 {object} Item \"Товар успешно создан\"","type":"blockquote","key":"9qmuj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":9,"offset":4,"style":"BOLD"}],"text":"Тег {object} указывает, что в ответе будет передан объект, описанный следующим тегом. А следующим тегом у нас Item, а объект Item - это наша пользовательская структура, содержащая json-объект.","type":"unstyled","key":"6aagl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Взглянем вновь на написанные для обработчика аннотации:","type":"unstyled","key":"9rs2m"},{"data":{"image":{"id":"670cc8c17584c1399f70615c"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации обработчика","type":"atomic:image","key":"eumo1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Теперь уже, думаю, с новым пониманием того, что здесь указано.","type":"unstyled","key":"3rf6s"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разобрались с аннотациями. Запускаем автоматическую генерацию спецификации по стандарту OpenAPI командой swag init в терминале:","type":"unstyled","key":"94ll0"},{"data":{"image":{"id":"670b57be3f6abd2101380c3d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в терминале","type":"atomic:image","key":"8uqk4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На иллюстрации мы запустили генерацию документации, получили логи документации, посмотрели содержимое каталога где должна создаться документация и начало содержимого одного из файлов.","type":"unstyled","key":"e565u"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Может показаться, что мы пишем какой-то непонятный код в виде комментариев Swagger: для чего? Для того, чтобы получить другой код (фрагмент которого представлен в терминале)? А почему бы не убрать из цепочки транслятор. Можно относится к этому так:","type":"unstyled","key":"4up8v"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"При написании комментариев swagger, мы создаём высокоуровневое описание API, а библиотека swaggo выполняет роль интерпретатора, который использует наши аннотации для написания более низкоуровневого кода, понятного компьютеру. ","type":"blockquote","key":"atkrh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Написание swagger-аннотаций в коде намного проще и гораздо быстрее, чем писать спецификацию на API по стандарту OpenAPI вручную. ","type":"blockquote","key":"1jeki"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":30,"offset":0,"style":"BOLD"}],"text":"3.2.2. Работа в Swagger Editor","type":"unstyled","key":"79fm2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Перейдём в браузере в Swagger Editor по пути https://editor.swagger.io/ и вставим в неё сгенерированную спецификацию. Результат:","type":"unstyled","key":"ekhgr"},{"data":{"image":{"id":"670b580c353dbb6d0f924f04"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа со Swagger Edior","type":"atomic:image","key":"5pgp1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Йуху! Мы создали нашу первую спецификацию по стандарту OpenAPI методом автоматической генерации. Можно раскрыть ручку POST и посмотреть что там:","type":"unstyled","key":"55mco"},{"data":{"image":{"id":"670b74f8072f907d53a07a07"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа со Swagger Edior ","type":"atomic:image","key":"f8q0b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пока здесь нет понятных примеров запросов и кодов статусов возможных ошибок, заголовков - но это демо-версия. Со всем этим разберёмся далее.","type":"unstyled","key":"aohcl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Что ж, мы протестировали команды swagger и создали работающую спецификацию, идём дальше. ","type":"unstyled","key":"8aqrl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":60,"offset":0,"style":"BOLD"}],"text":"3.2.3. Доработка Swagger-аннотаций обработчика POST-запросов","type":"unstyled","key":"bijau"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.2.3.1. Добавим описание нашему обработчику:","type":"unstyled","key":"6mk9k"},{"data":{"image":{"id":"670cca3db3d7114d4cfa542e"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"ag7u0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"После генерации спецификации, этот код будет выглядеть в Swagger Editor так (выделил текст):","type":"unstyled","key":"bnt15"},{"data":{"image":{"id":"670ccb0bd526d47b7146d8fc"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации API","type":"atomic:image","key":"73hjj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.2.3.2. Добавим тег в шапку","type":"unstyled","key":"13fjb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Чтобы в шапке был тег не default, а осмысленный, добавим тег item. Он нам понадобиться, чтобы упростить понимание что происходит при обращении по /home/create_item:","type":"unstyled","key":"2unlg"},{"data":{"image":{"id":"670ccb72710dce16019da4de"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"afiud"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"После генерации спецификации, этот код будет выглядеть в Swagger Editor так:","type":"unstyled","key":"8jig"},{"data":{"image":{"id":"670ccbb37584c1399f74b8d8"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации API","type":"atomic:image","key":"5q0c8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.2.3.3. Добавим пример для запроса","type":"unstyled","key":"3jhet"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напомню, как сейчас выглядит визуализация спецификации в части информации о запросе:","type":"unstyled","key":"7uefu"},{"data":{"image":{"id":"670cce0af6579240bb0133d5"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация упрощённой документации API","type":"atomic:image","key":"49hoh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Есть возможность указывать не стандартные типы для полей json-объекта, а конкретные цифры и текст: это упрощает понимание API. В ReadMe хитро и как-бы вскользь указано описание этого функционала: нужно доработать нашу структуру, а конкретно - добавить к json-описанию поле example - оно должно называться именно так, и описание к нему, например:","type":"unstyled","key":"61irl"},{"data":{"image":{"id":"670ccec8b3d7114d4c0238ff"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"72h56"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"После генерации спецификации, её визуализация будет выглядеть так:","type":"unstyled","key":"bq1ug"},{"data":{"image":{"id":"670ccf9245d6d72caac54d9f"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации API","type":"atomic:image","key":"ebnhn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Согласитесь, информация нагляднее.","type":"unstyled","key":"6t8ai"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.2.3.4. Доработаем ответ","type":"unstyled","key":"ab3rv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напомню, как выглядит сейчас визуализация спецификации API:","type":"unstyled","key":"fsu6q"},{"data":{"image":{"id":"670cd0bc353dbb6d0f4941ee"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация старой версии API","type":"atomic:image","key":"5td5b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Так выглядит аннотация, отвечающая за блок Example Value визуализации:","type":"unstyled","key":"6vmn3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Success 201 {object} Item ","type":"blockquote","key":"6fd19"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вспомним код, формирующий ответ на POST-запрос, вот его финальная часть:","type":"unstyled","key":"cn31d"},{"data":{"image":{"id":"670cd1443f6abd2101e3b0da"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"7emrp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Суть в чём: на запрос POST по REST нужно возвращать идентификатор созданного ресурса при успешном выполнении запроса, а не информацию о созданном товаре - как указано на текущий момент в спецификации API. ","type":"unstyled","key":"egjok"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В моём случае, идентификатор - это имя созданного файла, а по спецификации API мы возвращаем в теле ответа тело запроса. Некорректно.","type":"unstyled","key":"f1jof"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Что здесь можно сделать: написать что-то такое:","type":"unstyled","key":"91fkc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Success 201 {object} string","type":"blockquote","key":"ss3l"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Чем нас не устраивает такая аннотация? В ней нет примера возвращаемого ресурса. Я так и не нашёл способа создать пример, кроме как добавить тег example к json-объекту. Поэтому я пошёл путём создания новой структуры с соответствующим тегом и возвращением её:","type":"unstyled","key":"3nob4"},{"data":{"image":{"id":"670cd1f2551d0514029824bb"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"9u3eq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"И текст аннотаций:","type":"unstyled","key":"mj9e"},{"data":{"image":{"id":"670cd20bf6579240bb073d94"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации в коде","type":"atomic:image","key":"8uff2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"После этих изменений, сгенерируем документацию API и посмотрим, как она выглядит:","type":"unstyled","key":"7jjrm"},{"data":{"image":{"id":"670cd2364ac7562f9e4cd9f1"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация документации API","type":"atomic:image","key":"4g2qs"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Меня это устраивает. Идём дальше.","type":"unstyled","key":"7eug9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.2.3.5. Коды ошибок","type":"unstyled","key":"60eg8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Добавим теги для ошибок. По аналогии с предыдущим, успешным ответом, можно предположить что-то такое:","type":"unstyled","key":"77d25"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Success 400 {object} string","type":"blockquote","key":"1rbaa"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"ну и указать комментарий","type":"unstyled","key":"7j80s"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":43,"offset":0,"style":"ITALIC"}],"text":"// @Success 400 {object} string \"Ошибка валидации данных\"","type":"unstyled","key":"4uvkk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Как это будет выглядеть:","type":"unstyled","key":"8p8o5"},{"data":{"image":{"id":"670cd2ca03818b697396bfe3"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация документации API","type":"atomic:image","key":"3sr7q"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Мне не нравится в поле Example Value тип \"string\". Как его убрать оттуда? Можем вместо типа данных указать nil, и всё получится:","type":"unstyled","key":"e1l1j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @Failure 400 {object} nil \"Ошибка валидации данных\"","type":"blockquote","key":"b5v3a"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем все аннотации на ошибки, возвращаемые нашим обработчиком:","type":"unstyled","key":"67mo6"},{"data":{"image":{"id":"670cd36e4ac7562f9e4eec81"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации в коде","type":"atomic:image","key":"4golr"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Генерируем спецификацию, проверяем в визуальном редакторе:","type":"unstyled","key":"8psd0"},{"data":{"image":{"id":"670cd39bede5c5515ae549ed"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация документации API ","type":"atomic:image","key":"adejm"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Меня такая документация устраивает.","type":"unstyled","key":"d8jfv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Мы написали расширенную документацию на обработчик POST-запроса. Если попрактиковаться - это просто, а главное - наглядно для других специалистов.","type":"unstyled","key":"auq17"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем в таком же духе документацию на остальные обработчики.","type":"unstyled","key":"bk39l"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Крайне рекомендую своими руками также написать документацию на каждый обработчик, чтобы научиться инструментам Swagger.","type":"unstyled","key":"emko7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.3. Документация на обработчик DELETE-запроса","type":"header-three","key":"5011f"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации выглядят так:","type":"unstyled","key":"1crkt"},{"data":{"image":{"id":"670d5b63bea06939b616a36b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swagger-аннотации к коду ","type":"atomic:image","key":"d5ihf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":3,"offset":67,"style":"ITALIC"}],"text":"Что здесь интересного: добавлен параметризованную часть эндпоинта {id}, и убрал аннотацию @Accept, т.к. клиент не передаёт информации в теле запроса.","type":"unstyled","key":"eg5b9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Выглядеть это будет так:","type":"unstyled","key":"nend"},{"data":{"image":{"id":"670d5e9666e8be14554d0ada"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации API","type":"atomic:image","key":"ccvg0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Кстати, в предыдущем пункте не указал - можно \"поиграть\" и сделать пробный запрос, нажав кнопку Try it out:","type":"unstyled","key":"2nrj1"},{"data":{"image":{"id":"670d5edd0635e43f4a15420b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Работа в Swagger Editor","type":"atomic:image","key":"e797k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"При заполнении требуемых API полей (в данном случае заполнил только поле id - указал фрукт kiwi), Swagger Editor сформировал запрос.","type":"unstyled","key":"fkkgk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пока писал аннотации, понял что обработчики написаны с ошибкой в части типа возвращаемого клиенту контента. Возьмём сперва предыдущий обработчик - для POST-запроса, вот его код:","type":"unstyled","key":"e46g8"},{"data":{"image":{"id":"670d58db2667ca7f11a4ee23"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код обработчика POST-запросов","type":"atomic:image","key":"7dtcl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В строке 34 мы указали тип возвращаемых значений application/json, а сами в ошибках не возвращаем то возвращаем строку, т.е. тип text/plain, то не возвращаем ничего (кроме кода статуса). Это некорректно, и если мы хотим возвращать текст ошибки, то нужно преобразовывать их в json-объект, а не надеяться на продвинутый клиент, который может обработать контент несоответствующего типа согласно переданному сервером заголовку.","type":"unstyled","key":"df770"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вернёмся к обработчику DELETE-запросов, вот его код:","type":"unstyled","key":"40ovp"},{"data":{"image":{"id":"670d599a251db51a6c72e200"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код обработчика DELETE-запросов","type":"atomic:image","key":"aqvri"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Здесь мы указываем тип возвращаемого контента клиенту, как простой текст, т.е. text/plain. В действительности, мы возвращаем текст, только для ошибок, а при успешном выполнении кода - ничего не возвращаем (кроме кода статуса). Ошибка ли это? Нет, это не ошибка.","type":"unstyled","key":"9aq8j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.4. Документация на обработчик PATCH-запроса","type":"header-three","key":"astj6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swagger-аннотации к обработчику выглядят так:","type":"unstyled","key":"eeiie"},{"data":{"image":{"id":"670dda19d526d47b71b91c92"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации к коду","type":"atomic:image","key":"a0i0p"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Чтобы добавить пример заполнения тела запроса (см. стр. 154 на иллюстрации), создал структуру:","type":"unstyled","key":"fib5c"},{"data":{"image":{"id":"670ddb174281034c235e0ce2"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"2mov8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Что здесь ещё интересного: когда писал аннотации, обратил внимание, что обработчик не возвращает ошибку 500, хотя она возможна. В спецификации я прописал это, а в коде пока такой реализации нет.","type":"unstyled","key":"fpq1q"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вот так, полезно писать документацию, чтобы выявить ошибки. Хотя на это есть тесты, и их тоже нужно писать, и выявленное отсутствие обработки ошибки сервера - это одна из причин, почему тесты обязательны.","type":"unstyled","key":"thsq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сгенерируем спецификацию, посмотрим на неё в Swagger Editor:","type":"unstyled","key":"5f4q4"},{"data":{"image":{"id":"670dda9d03818b6973faed19"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Первая часть визуализации спецификации API","type":"atomic:image","key":"aq9f5"},{"data":{"image":{"id":"670ddab75dc4d803ee3b726b"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вторая часть визуализации спецификации API","type":"atomic:image","key":"6h08q"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Документация меня устраивает, идём к следующему обработчику.","type":"unstyled","key":"7ico5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.5. Документация на обработчик PUT-запроса","type":"header-three","key":"a7fbc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем swagger-аннотации:","type":"unstyled","key":"2esep"},{"data":{"image":{"id":"670dddc560075234caf20577"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации к коду","type":"atomic:image","key":"fou5u"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Что здесь интересного понял, когда заполнял аннотации: логика обработки POST-запроса такова, что мы создаём id с привязкой к наименованию ресурса, т.е. наименованию товара. Это не лучшая практика, и вот почему:","type":"unstyled","key":"cm1t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"При смене наименования товара, у нас фактически изменился id ресурса, и по идее нужно в ответ PUT-запросу возвращать обновлённый id. Но у нас не создавался новый ресурс, и это не соответствует принципам REST.","type":"blockquote","key":"36s20"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Короче, по-хорошему нужно изменить логику. Например, для идентификатора ресурса использовать не наименование товара, а хеш, который будет формироваться так: наименование товара + время получения запроса. Так мы получим практически уникальное наименование файла, в котором храним цену. ","type":"unstyled","key":"99au7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Ладно, возвращаемся к спецификации. Сгенерируем её и посмотрим:","type":"unstyled","key":"7sid3"},{"data":{"image":{"id":"670ddf0c0635e43f4a73615d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Первая часть визуализации спецификации API","type":"atomic:image","key":"7fm36"},{"data":{"image":{"id":"670ddf234281034c2360939d"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вторая часть визуализации спецификации API","type":"atomic:image","key":"2093j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Всё в порядке, переходим к следующему обработчику.","type":"unstyled","key":"27nf6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.6. Документация на обработчик GET-запроса","type":"header-three","key":"can3a"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Напишем swagger-аннотации:","type":"unstyled","key":"7qa1v"},{"data":{"image":{"id":"670de1254ac7562f9eb6cf26"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации к коду","type":"atomic:image","key":"c1kb0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Смотрим, как выглядит визуализация в Swagger Editor:","type":"unstyled","key":"8l3g8"},{"data":{"image":{"id":"670de14d965d9b718f3a5600"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Первая часть визуализации","type":"atomic:image","key":"c857v"},{"data":{"image":{"id":"670de15e1b26eb3bf394d9e8"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вторая часть визуализации","type":"atomic:image","key":"dsp97"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Что ж, документация на все обработчики готова. Теперь я хочу обновить swagger-аннотации к общему описанию проекта: затронуть больше доступных тегов.","type":"unstyled","key":"b3prn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.6. Расширяем общее описание проекта","type":"header-three","key":"34qb8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Сейчас, с документированием обработчиков, спецификация API в Swagger Editor выглядит так:","type":"unstyled","key":"7k7g"},{"data":{"image":{"id":"670de1d239347443d0a1eb55"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации","type":"atomic:image","key":"bu8o8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации к общему описанию сейчас выглядят так:","type":"unstyled","key":"8tqpn"},{"data":{"image":{"id":"670de1fed526d47b71be0625"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации к коду","type":"atomic:image","key":"84mc0"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Здесь указаны 8 swagger-аннотаций. В ReadMe библиотеки Swaggo для общего описания проекта предусмотрено 22 аннотации. Используем этот функционал по-максимуму и напишем аннотации:","type":"unstyled","key":"bmfkf"},{"data":{"image":{"id":"670e0c154281034c238c98e2"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Аннотации к коду","type":"atomic:image","key":"2536t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализируем спецификацию:","type":"unstyled","key":"g2e5"},{"data":{"image":{"id":"670df80ebea06939b6988754"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации API","type":"atomic:image","key":"7fle6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Все эти поля определены в ReadMe библиотеки Swaggo, продублирую свою интерпретацию из ReadMe, а после перечня дополню своими соображениями по сложным аннотациям. Также в тексте перечня ниже в скобках фразой \"был ранее\" обозначено, что эти аннотации были в первой версии описания проекта:","type":"unstyled","key":"4007e"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":6,"offset":0,"style":"BOLD"}],"text":"@title: название API или проекта (был ранее).","type":"ordered-list-item","key":"ahpas"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":8,"offset":0,"style":"BOLD"}],"text":"@version: версия API или проекта (был ранее).","type":"ordered-list-item","key":"5pelf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":12,"offset":0,"style":"BOLD"}],"text":"@description: описание API, объясняющее назначение и функционал (был ранее).","type":"ordered-list-item","key":"cve4c"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":15,"offset":0,"style":"BOLD"}],"text":"@termsOfService: URL для условий предоставления услуг. Это может быть юридическая информация о том, как и когда можно использовать API, ограничения ответственного использования и тому подобное.","type":"ordered-list-item","key":"9ev28"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":13,"offset":0,"style":"BOLD"}],"text":"@contact.name: имя контактного лица или разработчика (был ранее).","type":"ordered-list-item","key":"93sdt"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":12,"offset":0,"style":"BOLD"}],"text":"@contact.url: URL для обратной связи, например, GitHub, (был ранее).","type":"ordered-list-item","key":"aq88"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":14,"offset":0,"style":"BOLD"}],"text":"@contact.email: Email-адрес для связи (был ранее).","type":"ordered-list-item","key":"2t5u3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":13,"offset":0,"style":"BOLD"}],"text":"@license.name: название лицензии, под которой выпущен API (например, MIT). Лицензия определяет, как другие могут использовать код, что важно для Open Scource проектов.","type":"ordered-list-item","key":"9ado5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":12,"offset":0,"style":"BOLD"}],"text":"@license.url: URL, по которому можно найти текст лицензии.","type":"ordered-list-item","key":"2h2j3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":5,"offset":0,"style":"BOLD"}],"text":"@host: хост, на котором развернут API (был ранее).","type":"ordered-list-item","key":"ben3k"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":9,"offset":0,"style":"BOLD"}],"text":"@BasePath: базовый путь для API, обычно используется для определения начального пути для эндпоинтов (был ранее).","type":"ordered-list-item","key":"2j34v"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":0,"style":"BOLD"}],"text":"@accept: перечень форматов, которые API принимает (например, json, xml, plain) - обратите внимание, перечисление форматов в аннотации через пробел.","type":"ordered-list-item","key":"8pjlq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":8,"offset":0,"style":"BOLD"}],"text":"@produce: перечень форматов, которые API возвращает.","type":"ordered-list-item","key":"62bsb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"@query.collection.format: формат, используемый для определения типа массива данных в запросах, если предусмотрено API (например, multi для передачи нескольких значений) - см. скриншот из ReadMe библиотеки Swaggo и дополнительные разъяснения ниже.","type":"ordered-list-item","key":"4g2s5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":8,"offset":0,"style":"BOLD"}],"text":"@schemes: протоколы, поддерживаемые вашим API (например, http, https) - обратите внимание, в аннотации перечисление протоколов (если оно есть) выполняется через пробел.","type":"ordered-list-item","key":"1lrg4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":25,"offset":0,"style":"BOLD"}],"text":"@externalDocs.description: описание внешней документации, связанной с API - например, чтобы дополнительно прояснить некоторые моменты. Эта строка используется, когда есть, например, специальные руководства по работе с API.","type":"ordered-list-item","key":"2hrl2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":17,"offset":0,"style":"BOLD"}],"text":"@externalDocs.url: URL для внешней документации.","type":"ordered-list-item","key":"aibcp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":0,"style":"BOLD"}],"text":"@x-name: пользовательское расширение для документации, может быть использовано для добавления специфической информации. Эта аннотация предназначена для случаев, когда нужно добавить специфическую информацию, которая не вписывается в стандартные аннотации. Она может быть полезна для разработчиков API, чтобы включить метаданные или специальные расширенные функции.","type":"ordered-list-item","key":"a1rn6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":9,"offset":0,"style":"BOLD"}],"text":"@tag.name: название тега для группировки эндпоинтов (например, items).","type":"ordered-list-item","key":"f3qdj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":16,"offset":0,"style":"BOLD"}],"text":"@tag.description: описание тега.","type":"ordered-list-item","key":"d5dkt"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":13,"offset":0,"style":"BOLD"}],"text":"@tag.docs.url: URL для документации, связанной с тегом.","type":"ordered-list-item","key":"ec7kv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":21,"offset":0,"style":"BOLD"}],"text":"@tag.docs.description: описание документации по тегу.","type":"ordered-list-item","key":"cei1j"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Теперь разберём спорные, или просто, вызывающие сложности, аннотации.","type":"unstyled","key":"e3dvh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":16,"offset":0,"style":"BOLD"},{"length":27,"offset":17,"style":"BOLD"}],"text":"@termsOfService и @license.name/@license.url - не разобрался, чем они отличаются. Вероятно, если у вас какая-то нестандартная лицензия - нужно указать url для её чтения в аннотации @termsOfService.","type":"unstyled","key":"5ts8f"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"@query.collection.format - эта аннотация управляет тем, как API ожидает получение массивов параметров в запросах - если ожидает, как я понимаю. Вот что говорится об этом в ReadMe библиотеки Swaggo:","type":"unstyled","key":"5i8k9"},{"data":{"image":{"id":"670df34b60075234ca02cba0"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент ReadMe библиотеки Swaggo","type":"atomic:image","key":"2svl6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разберём форматы на примерах:","type":"unstyled","key":"f447p"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"csv (Comma-Separated Values): использует запятые для разделения значений.Пример: GET /items?ids=1,2,3","type":"blockquote","key":"s7p5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"ssv (Space-Separated Values): использует пробелы для разделения значений.Пример: GET /items?ids=1 2 3","type":"blockquote","key":"9795i"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"tsv (Tab-Separated Values): использует табуляции для разделения значений.Пример: GET /items?ids=1\\t2\\t3","type":"blockquote","key":"bmnoo"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"pipes: использует символы \"вертикальная черта\" для разделения значений.Пример: GET /items?ids=1|2|3","type":"blockquote","key":"79lke"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"multi: позволяет отправлять одно и то же имя параметра множество раз, в котором каждый экземпляр параметра представлен отдельно.Пример: GET /items?id=1&id=2&id=3","type":"blockquote","key":"cd4fs"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"У меня в API нет поддержания массива в запросах. А теперь, когда посмотрели примеры форматов, если ранее с ними знакомы не были - теперь становится понятно, что за массив данных в запросах определяет аннотация @query.collection.format. ","type":"unstyled","key":"3s1lb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":10,"style":"BOLD"}],"text":"Аннотация @x-name - это документирование API не по стандарту OpenAPI, и визуализироваться в Swagger Editor она не будет. Она может быть полезна, если нужно передать дополнительные данные, которые затруднительно выразить стандартными аннотациями OpenAPI. Например, у себя я ввёл такую запись:","type":"unstyled","key":"16r3h"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"// @x-name {\"environment\": \"production\", \"version\": \"1.0.0\", \"team\": \"backend\"}","type":"blockquote","key":"d6ice"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Суть её в чём - данные передаются как json-объект, а значение полей я предполагаю такое: ","type":"unstyled","key":"678ou"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"environment: указывает, в каком окружении работает API (например, production или development).","type":"unordered-list-item","key":"4ascf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"version: версия API, которая может быть полезна для отслеживания изменений в зависимости от окружения.","type":"unordered-list-item","key":"6dm6v"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"team: название команды, которая отвечает за разработку данного API.","type":"unordered-list-item","key":"anv7r"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Разобрались со всеми аннотациями для общего описания. Я, пожалуй, уберу из своей спецификации несколько аннотаций, которые не актуальны для моего API и могут сбивать с толку:","type":"unstyled","key":"bchvk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"@query.collection.format, т.к. у меня API не поддерживает массив запросов;","type":"unordered-list-item","key":"75qu5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"@termsOfService - у меня нет документации, определяющей особые условия использования API, неоговоренные стандартной лицензией.","type":"unordered-list-item","key":"akp83"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Выглядит теперь документация так:","type":"unstyled","key":"12ug0"},{"data":{"image":{"id":"670e114417ebdf0fe158fa32"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация API","type":"atomic:image","key":"dd02o"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На этом основной разбор проектирования документации на API по стандарту OpenAPI закончен. Далее посмотрим, что ещё интересного можно добавить в разработку документации API.","type":"unstyled","key":"2hq6"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"3.7. Интеграция Swagger UI","type":"header-three","key":"20rre"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Мы можем подключить Swagger UI на нашем сервере, чтобы пользователи могли сразу видеть интерактивную документацию API из браузера, при обращении к серверу, а не копировать спецификацию API на сайт Swagger Edotor.","type":"unstyled","key":"5qbta"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Воспользуемся сторонней библиотекой http-swagger - это обёртка стандартного пакета net/http для автоматической генерации API:","type":"unstyled","key":"d6rgp"},{"data":{"image":{"id":"670eae899e955a2f22e2c496"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пакет http-swagger: https://pkg.go.dev/github.com/swaggo/http-swagger@v1.3.4#section-readme","type":"atomic:image","key":"dc98r"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Допишем обработчик в функцию main:","type":"unstyled","key":"9rmcg"},{"data":{"image":{"id":"670eb0571803eb3b4687c8ce"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"dad2i"},{"data":{"image":{"id":"670eaf1567605b716b2bf8f1"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Код","type":"atomic:image","key":"40mt4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Теперь, когда мы запустим сервер и в браузере перейдём по url ","type":"unstyled","key":"2eudk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"http://localhost:8080/swagger/","type":"blockquote","key":"1f2ql"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"мы вызываем функцию http.Handle(\"/swagger/\", ...), которая использует обработчик WrapHandler пакета http-swagger (httpSwagger). ","type":"unstyled","key":"6cfnt"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swagger UI будет автоматически загружать необходимые HTML/CSS/JS-файлы для отображения интерфейса в виде веб-страницы в браузере. ","type":"unstyled","key":"13rno"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Посмотрим, что находится в функции WrapHandler, а конкретно я хочу показать код, формирующий фронтенд:","type":"unstyled","key":"63cvv"},{"data":{"image":{"id":"670eb1bd05ca7518f4537bc9"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Начало описания функции WrapHanler сторонней библиотеки http-swagger","type":"atomic:image","key":"nmkq"},{"data":{"image":{"id":"670eb1fb05ca7518f453e322"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Окончание описания функции WrapHandler","type":"atomic:image","key":"9e3jg"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Как видим - в функции сохранён фронтенд, написанный на языке разметки html.","type":"unstyled","key":"aj2rc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Хорошо, немного посмотрели, что под капотом этой интересной функции, идём дальше.","type":"unstyled","key":"4iqs3"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"По-умолчанию Swagger UI требует спецификацию в формате json, поэтому мы также прописываем обработчик с эндпоинтом .../doc.json и используем специальную функцию для возвращения клиенту одного файла - ServeFile. Возвращаем мы .json-файл спецификации API по стандарту OpenAPI, сгенерированного автоматически на предыдущих шагах командой ","type":"unstyled","key":"lofh"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"swag init","type":"blockquote","key":"7jss9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Когда мы переходим на ","type":"unstyled","key":"davcj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"http://localhost:8080/swagger/","type":"blockquote","key":"bpi8o"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Swagger UI автоматически делает запрос к обработчику эндпоинта ","type":"unstyled","key":"6gifl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"/swagger/doc.json ","type":"blockquote","key":"e5j01"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"(это поведение Swagger UI по умолчанию). Это происходит потому, что в конфигурации Swagger UI задается URL спецификации, который по умолчанию указывает на doc.json. Почему я об этом подробно говорю? Т.к. по-умолчанию, команда swag init генерирует три файла:","type":"unstyled","key":"dc10d"},{"data":{"image":{"id":"670eb582c0fa4a16294bf643"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Генерируемые файлы командой swag init","type":"atomic:image","key":"dp8mf"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":30,"offset":59,"style":"ITALIC"}],"text":"Ладно, запустили сервер, перешли в браузер и ввели команду http://localhost:8080/swagger/ - смотрим, что получилось:","type":"unstyled","key":"5e8k0"},{"data":{"image":{"id":"670eb5cce17d0d53fe0be602"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Визуализация спецификации API","type":"atomic:image","key":"96atn"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Успех! Мы смогли настроить наш сервер так, чтобы он обрабатывал входящие запросы и через интерфейс Swagger UI, визуализировал нашу спецификацию в виде веб-страницы, как если бы мы копировали её вручную из файла и вставляли в соответствующее поле на сайте Swagger Editor. Удобно.","type":"unstyled","key":"4mner"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"На этом разбор автоматической генерации спецификации по стандарту OpenAPI считаю законченной с уточнением по безопасности.","type":"unstyled","key":"a9os4"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В ReadMe библиотеки Swaggo есть блок, посвящённый безопасности:","type":"unstyled","key":"6do6f"},{"data":{"image":{"id":"670eb7015511103965bd4498"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Фрагмент ReadMe библиотеки Swaggo","type":"atomic:image","key":"4jt2t"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Безопасность осуществляется через аутентификацию и/или авторизацию пользователя. Согласитесь - это полезная штука: без такой фичи любой пользователь может перейти по url и посмотреть документацию на наш сервер, это как если любой желающий может посмотреть паспорт или другие личные документы: опасно.","type":"unstyled","key":"dua6n"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Но аутентификацию и авторизацию я пока не изучал, не представляю какие есть способы для этого. Оставим это на домашнее задание.","type":"unstyled","key":"darig"},{"data":{},"depth":0,"entityRanges":[{"key":3,"length":5,"offset":29}],"inlineStyleRanges":[],"text":"Код приложения на GitHub >>> здесь <<<","type":"unstyled","key":"311bm"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"4. Дополнения","type":"header-two","key":"eduuk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В ходе написания публикации, я выявил недочёты и опечатки в аннотациях, которые по-хорошему нужно доработать в сервисе; в целом они не влияют на порядок действий для автоматической генерации спецификации API, поэтому в этом проекте код переделывать не буду, а в следующих учту недочёты, и сделаю сервисы лучше.","type":"unstyled","key":"30is7"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Получил обратную связь от опытного разработчика. Информация следующая:","type":"unstyled","key":"1ovd9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"1. Не нужно использовать snake_case в ручках, только kebab-case. Т.е. вместо ","type":"unstyled","key":"fo0uj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"/home/create_item","type":"blockquote","key":"b0ps9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"нужно писать","type":"unstyled","key":"4lfsj"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"/home/create-item","type":"blockquote","key":"6dt14"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"2. Ручки в ответ должны отдавать структуру, лучше json вида: OKResponse {status: ok, body: data} или ErrorResponse{ code: 500, message: error}, например:","type":"unstyled","key":"61uo1"},{"data":{"image":{"id":"670f4c56fab3b5209a974433"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Пример возвращения ошибки","type":"atomic:image","key":"blqg1"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Т.е. не просто статус кода в случае ошибки отдавать в ответе, а дополнительно json-объект. Может возникнуть вопрос: зачем это дублирование статуса. Возможный ответ:","type":"unstyled","key":"6e6bd"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Статус, устанавливаемый в заголовке при ответе сервера и статус json ответа, который будут ждать фронты и другие потребители ручек, будут благодарны, если будешь отдавать стандартизированный json ответ, если речь идёт об OpenAPI и сгенерированные на его основе методы и структуры данных.","type":"blockquote","key":"edina"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"5. Выводы","type":"header-two","key":"24n2u"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Идея публикации - научиться применять автоматическую генерацию спецификации API по стандарту OpenAPI, - выполнена. Значит ли это, что мы полностью освоили библиотеку Swaggo, даже со скидкой на отсутствие безопасности? Нет. Значит ли это, что мы освоили базовый функционал и часть ситуативного функционала библиотеки Swaggo для генерации спецификации API? Да.","type":"unstyled","key":"dcehs"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Также мы в процессе разработки сервера коснулись некоторых основ REST API. Постепенно наш уровень растёт, осваиваются новые инструменты, и мы развиваемся, как разработчики. ","type":"unstyled","key":"2tf95"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Благодарю, что дочитали эту публикацию до конца. Продолжаем развиваться технически, улучшать свой характер и у нас всё получится. Будем на связи. Успехов!","type":"unstyled","key":"feeqt"},{"data":{},"depth":0,"entityRanges":[{"key":4,"length":12,"offset":71}],"inlineStyleRanges":[],"text":"Бро, ты уже здесь? \uD83D\uDC49 Подпишись на канал для начинающих IT-специалистов «Войти в IT» в Telegram, будем изучать IT вместе \uD83D\uDC68‍\uD83D\uDCBB\uD83D\uDC69‍\uD83D\uDCBB\uD83D\uDC68‍\uD83D\uDCBB","type":"unstyled","key":"77tuo"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"","type":"marker","key":"z7JbWc3549rdIrvStuUF"}],"entityMap":{"0":{"data":{"url":"https://dzen.ru/a/ZuReWiEO4SVZP2Qc"},"mutability":"MUTABLE","type":"LINK"},"1":{"data":{"url":"https://dzen.ru/a/Y_XsgCFKcl9QZTTE"},"mutability":"MUTABLE","type":"LINK"},"2":{"data":{"url":"https://tenchat.ru/EvKly?utm_source=0ba3ed54-21b4-47c0-a974-5db7ab5d04d6"},"mutability":"MUTABLE","type":"LINK"},"3":{"data":{"url":"https://github.com/jedyEvgeny/sandbox/blob/main/Swagger-test/go-example_two/main.go"},"mutability":"MUTABLE","type":"LINK"},"4":{"data":{"url":"https://dzen.ru/away?to=https%3A%2F%2Ft.me%2F%2BZGac_D1V4wFjYzRi"},"mutability":"MUTABLE","type":"LINK"}}},"mentions":[]}