Меню

Як створити документацію API у поштарці?

how create api documentation postman

Спробуйте Наш Інструмент Для Усунення Проблем

Цей підручник пояснює, як створити гарну, стилізовану документацію з мінімальними зусиллями, використовуючи підтримку документації API, надану Інструментом листоноші:

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

Основною причиною цього є те, що документація - це спосіб спілкування з вашими користувачами.

  • Як слід використовувати ваш API?
  • Які всі коди стану підтримуються?
  • Які коди помилок?
  • Які типи методів піддаються?

Вся ця інформація необхідна кожному для використання або реалізації API для бажаних потреб.

=> Тут слідкуйте за простими навчальними циклами листонош.

Листоноша - Створення документації API

Як відкрити файли для сміття Windows 10

Postman надає просту у використанні методологію документації, а для базової документації - це так само просто, як натиснення кнопки в колекції Postman, і ви можете отримати загальнодоступну URL-адресу для своєї документації API.

Що ви дізнаєтесь:

Створення документації API у поштарці

Особливості документації

Основні особливості генератора документації Postman включають:

  • Він підтримує синтаксис розмітки. Markdown - це загальний синтаксис документації, який ви, як правило, помічали в будь-якому проекті Github. Це дозволяє зробити стилі та форматування тексту більш звичними та простішими.
  • Немає конкретного синтаксису / вимог до створення документації. Інформація про запити та збір використовується найкращим чином для формування документації.
  • Його можна опублікувати за загальнодоступною URL-адресою або в користувацькому домені (для корпоративних користувачів).
  • Генерує фрагменти коду для здійснення викликів до API різними мовами, такими як C #, PHP, Ruby, Python, Node тощо.

Створення документації

Генератор документів 'Поштовець' посилається на опис колекції, папки та індивідуального запиту та порівнює їх під час створення або створення документації для колекції.

Він використовує різні параметри запиту, такі як заголовки, параметри рядка запиту, параметри форми та вказує на використання цих значень у документації запиту.

Ось відеоурок:

Давайте створимо базову колекцію з 3 запитів, використовуючи той самий тестовий API, що й інші наші статті. Ми додамо деяку інформацію до опису колекції, а також до окремих запитів, а також створимо кілька прикладів запитів та відповідей, які також будуть зафіксовані під час створення документації.

Виконайте наведені нижче дії, щоб додати основну інформацію про запити, а потім створити документацію.

# 1) Створіть колекцію з 3 запитами, тобто зареєструйте користувача, зареєструйте користувача та отримайте користувача (див тут для корисних навантажень запиту та URL-адрес API).

# два) Тепер давайте додамо до колекції деяку інформацію у форматі націнки. Розцінка - це стандартний формат, який використовується майже для всієї документації в 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. Збереження відповіді як прикладу дозволяє генератору документації захопити його як частину самої документації.

Щоб зберегти приклад, натисніть “Надіслати” , щоб виконати запит, і на вкладці відповіді натисніть Зберегти відповідь -> Зберегти як приклад .

Зберегти приклад

Після збереження прикладу він зберігається в колекції і може бути доступний у будь-який час у майбутньому через Приклади посилання у конструкторі запитів.

# 5) Після того, як буде додано всю вищезазначену інформацію, давайте подивимося, як створити попередній перегляд документації.

Відкрийте опції колекції та натисніть “ Опублікувати документи '.

Опублікувати документи

Примітка: Важливо зазначити тут, що лише зареєстровані користувачі з Postman зможуть використовувати функцію Publish docs на Postman. Реєстрація безкоштовна, але її потрібно зробити через ваш електронний рахунок. Існують інші можливості / функції, такі як спільний доступ до колекцій та робочих областей, створення моніторів тощо, які додаються до зареєстрованих облікових записів.

# 6) Раз Опублікувати документи ”, Відкривається вкладка браузера з деталями колекції Postman (внутрішньо Postman розміщує цю колекцію на своїх власних серверах, крім локальної файлової системи користувача).

Збірник документації

Натисніть на “Попередній перегляд” для перегляду документації перед її публікацією.

' Опублікувати колекцію ”Посилання опублікує документацію за загальнодоступною URL-адресою. Зазвичай не рекомендується публікувати API, що мають конфіденційну інформацію про авторизацію, для публікації за загальнодоступною URL-адресою. Такі API можна публікувати за допомогою власних доменів з корпоративними обліковими записами Листоноші.

# 7) Подивимось, як виглядає попередній перегляд документації. Клацнувши “ Попередній перегляд документації ”Відкриває документацію в режимі попереднього перегляду, розміщеному на серверах Поштовика. Давайте подивимося, які різні деталі фіксуються в документації (як ми налаштовували в різних місцях. Наприклад , опис колекції, опис запиту та приклади).

Зразок документації листоноші

Опис запиту в Markdown

На наведених вище 2 скріншотах ви можете побачити, що вся інформація, яка була додана до колекції та описів запитів, фіксується у стилі розмітки у попередньому перегляді документації.

верхній безкоштовний конвертер YouTube в mp3

Крім того, документація за замовчуванням надає мовні прив’язки, як виділено, і це значно полегшує тих, хто хоче безпосередньо зробити запит API на вказаній мові.

# 8) Це також дозволяє виконувати дуже основні модифікації стилів, такі як зміна кольору тла, зміна кольору тла та переднього плану шаблонів заголовків тощо. Але загалом самого перегляду за замовчуванням достатньо, щоб опублікувати справді хороший набір документації, що охоплює багато важливі деталі про API.

Висновок

У цьому підручнику ми ознайомилися з підтримкою документації API, яку надає Postman, за допомогою якої ми можемо створити красиву, стилізовану документацію з мінімальними зусиллями.

Він також надає безліч хороших шаблонів та визначений користувачем стиль, який можна застосувати до згенерованих документів, а також дозволяє публікувати документацію до загальнодоступної URL-адреси.

Для приватних кінцевих точок API також передбачено публікацію документації у власному домені, який можна налаштувати для корпоративних облікових записів або користувачів.

Подальше читання = >> Як опублікувати Pact Contract to Pact Broker

=> Завітайте сюди, щоб навчитися листоноші з нуля.

Рекомендована література

^