Автор оригинала: Idris Adetunmbi.
Вы, вероятно, получили это точку, где вам нужно написать или публиковать документацию для вашей API, а затем узнать о Чугерс Быть самым популярным инструментом для такой вещи. Вы узнаете о чванство и планируете выполнить документацию как можно быстрее, но потом, работая с Swagger, кажется, так запутается, вы не знаете, с чего начать или как пойти о том, что вы думаете, должен быть тривиальной задачей.
Чтобы подумать о том, чтобы набрать документы вручную в редакторе Swarger боится вам так сильно, и тогда вы думаете, что вы должны пропустить эту документацию до позже или использовать другой инструмент.
Swagger имеет отличный набор инструментов для создания качественной документации API, но ее повсеместность в документации ECOSYSTEM делает его запутанным для большинства начинающих.
Достаточно анализа SWARGER, я перечисляю это в шагах, чтобы сделать урок легко следовать, так как процесс должен быть максимально простым.
Шаг I: Генерация документации с почтальоном
Введение в документацию API _Выберите, если вы хотите создать документацию для новой API или существующей коллекции или команды. Если вы создаете новую API to … _www.getpostman.com
Документация API через почтальон так же просто, как создание коллекции, выполнения запросов для каждой из ваших реализованных маршрутов, сохраняя каждый запрос в коллекцию, включая отзывы образцов (отзыв об ошибках и успех, чтобы сделать вашу документацию Rich) и экспортировать коллекцию.
Если бы это казалось много, снова прочитайте и просто следуйте шагам, как указано, мы не будем много говорить о документации API через почтальон, так как кажется почти тривиальной задачей, и сохранить этот учебник как можно более склонным к Другие учебники объясняют лучше, как это сделать.
Что на самом деле нужно на самом деле, на самом деле, это файл JSON (Postman Docs), который выводит через меню созданного сбора.
Экспорт коллекции почтальона
Шаг II: преобразование генерируемого почтальона до документов на Swagger или Specification Specification
Я обнаружил простую платформу, apimatic.io сделать это через поиск. Платформа требует, чтобы вы зарегистрировались в использовании их API трансформатор сервис Чтобы преобразовать файл JSON на наш желаемый выход (P̶R̶e̶f̶e̶r̶a̶b̶l̶y̶ ̶o̶p̶e̶n̶ ̶a̶p̶i̶ ̶v̶3̶.̶0̶).
Возможно, вы захотите покинуть выход по умолчанию (Open API/Swagger v2.0), который дает преобразователь (ранее предложенное Open API V3.0, кажется, сложно попробовать запросы с).
Шаг III: служение преобразованного файла через наше приложение
Этот шаг требует установки Swagger-ui-Express , довольно простой пакет, который делает фактическую работу по обслуживанию документации API. Основной изюминкой из пакетов документов является как показано ниже:
Шаг IV: Просмотр документации в браузере
Это не обязательно шаг, но тогда вы хотели бы увидеть, как выглядит документы в вашем браузере в зависимости от пути, указанного на шаге III – E.G. localhost: 3000/API-Docs
Образец документации API, созданная через почтальон и преобразована с апиматом
Несколько вещей, чтобы отметить
- Документация от почтальона должна быть максимально богатой, поскольку она определяет служенную документацию API в конце. Достаточно обратных откликов с одного маршрута.
- Согласился, это ленивый подход к генерированию документации API (не совсем ленивый, так как есть много, чтобы сделать с почтальоном). Документация может быть не так богата, создавая документы через редактор Swarger. Настоятельно рекомендуется редактировать преобразованный файл в редакторе Swarger.
- Отказ от ответственности на самом деле; Я обнаружил Apimatic через поиск Google, я в любом случае не в любом случае не связан с владельцами или платят, чтобы поговорить о платформе.
Я хотел бы узнать ваши мысли об этом посте и качество документации, которую вы получаете, чтобы сгенерировать с ним в комментариях.
Спасибо.