Меню

Как да създам API документация в пощальон?

how create api documentation postman

Този урок обяснява как да създадете добре изглеждаща, стилизирана документация с минимални усилия, използвайки поддръжката на документацията на API, предоставена от Postman Tool:

За всеки API, независимо дали е вътрешен или публичен, документацията е една от най-важните съставки за успеха му.

Основната причина за това е, че документацията е начинът, по който общувате с вашите потребители.

  • Как трябва да се използва API?
  • Кои всички кодове на състоянието се поддържат?
  • Кои са кодовете за грешки?
  • Какви всички видове методи са изложени?

Цялата тази информация е необходима за всеки, който използва или прилага API за желаната нужда.

=> Внимавайте тук за поредицата за обучение на прости пощальони.

Пощальон - Създаване на API документация

Postman предоставя лесна за използване методология на документацията, а за основната документация е толкова просто, колкото щракването върху бутон през колекцията Postman и можете да получите публичен URL адрес за вашата API документация.

прост алгоритъм за сортиране c ++

Какво ще научите:

Създаване на API документация в пощальон

Характеристики на документацията

Основните характеристики на генератора на документация на Postman включват:

  • Той поддържа синтаксис на маркиране. Markdown е общ синтаксис на документацията, който обикновено трябва да забелязвате при всеки проект на Github. Позволява да направите стилизирането и форматирането на текст по-познати и по-лесни.
  • Няма специфичен синтаксис / изисквания за създаване на документация. Информацията за заявките и събирането се използва по най-добрия начин за генериране на документация.
  • Той може да бъде публикуван в публичен URL адрес или в потребителски домейн (за корпоративни потребители).
  • Генерира кодови фрагменти за извършване на повиквания към API на различни езици като C #, PHP, Ruby, Python, Node и др.

Създаване на документация

Генераторът на документи на пощальон се отнася до описанието на колекцията, папката и индивидуалната заявка и ги съпоставя, докато създава или генерира документация за колекцията.

Той използва различни параметри на заявката като заглавки, параметри на нива на заявката, параметри на формуляра и показва използването на тези стойности в документацията на заявката.

Ето видео урок:

Нека създадем основна колекция с 3 заявки, използвайки същия тестов API като другите ни статии. Ще добавим малко информация към описанието на колекцията, както и към отделните заявки, а също така ще създадем някои примерни заявки и отговори, които също ще бъдат заснети при създаването на документацията.

Следвайте стъпките по-долу, за да добавите основна информация за заявките и след това да създадете документацията.

# 1) Създайте колекция с 3 заявки, т.е. регистриране на потребител, потребител за влизане и получаване на потребител (препратка тук за полезни натоварвания на заявки и URL адреси на API).

# две) Сега нека добавим малко информация във формат на намалена стойност към колекцията. Markdown е стандартен формат, който се използва за почти цялата документация в Github (За повече информация относно маркирането вижте тук ).

Ще добавим малко информация към описанието на колекцията във формата за намаление, както е показано по-долу.

Описание на колекцията във формат намаление

За да видите как изглежда маркирането, вижте уеб портала с отворен код тук.

Документация за маркиране

# 3) Сега ще добавим описанията към отделни заявки в колекцията. Подобно на колекцията, форматът за намаление се поддържа и за описанията на заявките (За по-подробна информация относно ръководството за намаление, вижте тук ).

Нека да видим извадка от една от заявките за крайна точка за регистрация на потребителя (Същото може да се приложи и към други заявки).

Текст на маркирането:

API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code

Предварителен преглед на Markdown:

Предварителен преглед на Markdown

# 4) За всички крайни точки на API, нека заснемем или запазим пример, който ще бъде използван от генератора на документация.

Пример не е нищо друго освен примерна заявка-отговор за разглеждане на заявката за API. Запазването на отговора като пример позволява на генератора на документация да го заснеме като част от самата документация.

За да запазите пример, натиснете „Изпращане“ за изпълнение на заявката и в раздела за отговор щракнете Save Response -> Save as Example .

Запазване на пример

След като примерът бъде запазен, той се запазва в колекцията и може да бъде достъпен по всяко време в бъдеще чрез Примери връзка в конструктора на заявки.

# 5) След като се добави цялата горепосочена информация, нека видим как да създадем визуализация на документация.

Отворете опциите за събиране и кликнете „ Публикуване на Документи ”.

Публикуване на Документи

Забележка: Тук е важно да се отбележи, че само регистрирани потребители с Postman ще могат да използват функцията Publish docs в Postman. Регистрацията е безплатна, но трябва да се извърши чрез вашия имейл акаунт. Има и други възможности / функции като споделяне на колекции и работни пространства, създаване на монитори и др., Които се добавят към регистрираните акаунти.

# 6) Веднъж ' Публикуване на Документи ”Се изпълнява, отваря се раздел на браузъра с подробности за колекцията на Postman (вътрешно Postman хоства тази колекция на собствените си сървъри, в допълнение към локалната файлова система на потребителя).

Събиране на документация

Кликнете върху „Преглед“ за да видите документацията, преди да бъде публикувана.

' Публикувай колекция ”Връзката ще публикува документацията до публично достъпен URL адрес. Обикновено не се препоръчва да се публикуват приложни програмни интерфейси (API) с чувствителна информация за оторизация, които да се публикуват на публичния URL адрес. Такива API могат да бъдат публикувани с помощта на персонализирани домейни с корпоративни акаунти на Пощальона.

# 7) Нека да видим как изглежда визуализацията на документацията. Щракване върху „ Преглед на документацията “Отваря документацията в режим на визуализация, който се хоства на сървърите на Postman. Нека да видим какви различни подробности са заснети в документацията (Както конфигурирахме на различни места. Например , описание на колекцията, описание на заявка и примери).

Пример за документация на пощальон

Заявка за описание в Markdown

В горните 2 скрийншота можете да видите, че цялата информация, която е била добавена към описанията на колекцията и заявките, се заснема в стил на маркиране в визуализацията на документацията.

Също така, документацията по подразбиране предоставя езикови обвързвания, както е подчертано и това улеснява много за някой, който иска директно да направи заявката за API на изброения език.

въпроси и отговори за интервю за api тестване

# 8) Също така ви позволява да извършвате много основни модификации на стила, като промяна на цвета на фона, промяна на цвета на фона и предния план на шаблоните на заглавките и т.н. Но като цяло самият изглед по подразбиране е достатъчен, за да публикувате наистина добър набор от документация, заснемащ много важни подробности за API.

Заключение

В този урок разгледахме поддръжката на документацията за API, предоставена от Postman, с помощта на която можем да създадем добре изглеждаща, стилизирана документация с минимални усилия.

Той също така позволява много добри шаблони и дефиниран от потребителя стил, които могат да бъдат приложени към генерираните документи и позволява публикуване на документация и на публичен URL адрес.

За частни крайни точки на API има и разпоредба за публикуване на документация в потребителски домейн, който може да бъде конфигуриран за корпоративни акаунти или потребители.

Допълнително четене = >> Как да публикувам договор за договор с брокер на Pact

=> Посетете тук, за да научите пощальон от нулата.

Препоръчително четене

^