how create api documentation postman
W tym samouczku wyjaśniono, jak stworzyć ładną, stylizowaną dokumentację przy minimalnym wysiłku, korzystając z obsługi dokumentacji API zapewnianej przez narzędzie Postman:
W przypadku każdego interfejsu API, zarówno wewnętrznego, jak i publicznego, dokumentacja jest jednym z najważniejszych elementów jego sukcesu.
Głównym tego powodem jest dokumentacja to sposób, w jaki komunikujesz się z użytkownikami.
- Jak powinien być używany Twój interfejs API?
- Jakie wszystkie kody stanu są obsługiwane?
- Jakie są kody błędów?
- Jakie typy metod są ujawniane?
Wszystkie te informacje są niezbędne, aby każdy mógł używać lub wdrażać API zgodnie z potrzebami.
=> Obejrzyj serię prostych szkoleń listonosza tutaj.
Inicjalizacja zmiennej statycznej c ++
Postman zapewnia łatwą w użyciu metodologię dokumentacji, a w przypadku podstawowej dokumentacji wystarczy kliknąć przycisk w kolekcji Postman, aby uzyskać publiczny adres URL dokumentacji interfejsu API.
Czego się nauczysz:
Tworzenie dokumentacji API w programie Postman
Funkcje dokumentacji
Najważniejsze cechy generatora dokumentacji Postman obejmują:
- Obsługuje składnię markdown. Markdown to ogólna składnia dokumentacji, którą zwykle należy zauważyć w każdym projekcie Github. Dzięki temu stylizacja i formatowanie tekstu są bardziej znane i łatwiejsze.
- Brak określonej składni / wymagań dotyczących tworzenia dokumentacji. Informacje o żądaniach i zbieraniu są wykorzystywane w najlepszy sposób do generowania dokumentacji.
- Można go opublikować pod publicznym adresem URL lub w domenie niestandardowej (dla użytkowników korporacyjnych).
- Generuje fragmenty kodu do wykonywania wywołań interfejsu API w różnych językach, takich jak C #, PHP, Ruby, Python, Node itp.
Tworzenie dokumentacji
Generator dokumentów Postman odnosi się do opisu kolekcji, folderu i indywidualnego wniosku i zestawia je podczas tworzenia lub generowania dokumentacji do kolekcji.
Korzysta z różnych parametrów żądania, takich jak nagłówki, parametry ciągu zapytania, parametry formularza i wskazuje użycie tych wartości w dokumentacji żądania.
Oto samouczek wideo:
Utwórzmy podstawową kolekcję z trzema żądaniami przy użyciu tego samego testowego interfejsu API, co w innych naszych artykułach. Dodamy trochę informacji do opisu kolekcji, a także do poszczególnych wniosków, a także utworzymy przykładowe żądania i odpowiedzi, które również zostaną uchwycone podczas tworzenia dokumentacji.
Wykonaj poniższe kroki, aby dodać podstawowe informacje o żądaniach, a następnie utworzyć dokumentację.
# 1) Utwórz kolekcję z 3 żądaniami, tj. Zarejestruj użytkownika, zaloguj użytkownika i uzyskaj użytkownika (patrz tutaj dla ładunków żądań i adresów URL API).
#dwa) Teraz dodajmy do kolekcji trochę informacji w formacie przecen. Markdown to standardowy format, który jest używany w prawie całej dokumentacji na Githubie (aby uzyskać więcej informacji na temat promocji, zobacz tutaj ).
Dodamy trochę informacji do opisu kolekcji w formacie przecen, jak poniżej.
Aby zobaczyć, jak wygląda przecena, odwiedź portal internetowy typu open source tutaj.
# 3) Teraz dodamy opisy do poszczególnych zapytań w kolekcji. Podobnie jak w przypadku kolekcji, format przeceny jest obsługiwany również w przypadku opisów żądań (aby uzyskać bardziej szczegółowe informacje tutaj ).
Zobaczmy próbkę jednego z żądań punktu końcowego Zarejestruj użytkownika (to samo można zastosować do innych żądań).
Tekst Markdown:
API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code
Podgląd Markdown:
# 4) Dla wszystkich punktów końcowych API, przechwyćmy lub zapiszmy przykład, który będzie używany przez generator dokumentacji.
Przykładem jest nic innego jak przykładowa odpowiedź na żądanie API. Zapisanie odpowiedzi jako przykładu umożliwia generatorowi dokumentacji przechwycenie jej jako części samej dokumentacji.
Aby zapisać przykład, naciśnij 'Wysłać' , aby wykonać żądanie i na karcie odpowiedzi kliknij Zapisz odpowiedź -> Zapisz jako przykład .
Po zapisaniu przykładu zostanie on utrwalony w kolekcji i będzie można uzyskać do niego dostęp w dowolnym momencie w przyszłości za pośrednictwem pliku Przykłady łącze w konstruktorze żądań.
# 5) Po dodaniu wszystkich powyższych informacji zobaczmy, jak utworzyć podgląd dokumentacji.
Otwórz opcje kolekcji i kliknij „ Opublikuj dokumenty ”.
Uwaga: Ważną rzeczą do zapamiętania jest to, że tylko zarejestrowani użytkownicy z Postman będą mogli korzystać z funkcji Publikuj dokumenty w programie Postman. Rejestracja jest bezpłatna, ale należy ją przeprowadzić za pośrednictwem konta e-mail. Istnieją inne możliwości / funkcje, takie jak udostępnianie kolekcji i obszarów roboczych, tworzenie monitorów itp., Które są dodawane do zarejestrowanych kont.
# 6) Pewnego razu ' Opublikuj dokumenty ”, Otwiera się karta przeglądarki ze szczegółami kolekcji Postman (wewnętrznie Postman przechowuje tę kolekcję na swoich własnych serwerach, a także w lokalnym systemie plików użytkownika).
Kliknij 'Zapowiedź' aby wyświetlić dokumentację przed jej opublikowaniem.
' Opublikuj kolekcję ”Link spowoduje opublikowanie dokumentacji pod publicznie dostępnym adresem URL. Generalnie nie zaleca się publikowania interfejsów API zawierających poufne informacje autoryzacyjne do publikowania pod publicznym adresem URL. Takie interfejsy API można publikować przy użyciu domen niestandardowych z kontami przedsiębiorstwa Listonosza.
# 7) Zobaczmy, jak wygląda podgląd dokumentacji. Kliknięcie „ Podgląd dokumentacji ”Otwiera dokumentację w trybie podglądu hostowanym na serwerach Postman. Zobaczmy, jakie różne szczegóły są zawarte w dokumentacji (zgodnie z konfiguracją w różnych miejscach. Na przykład , opis kolekcji, opis wniosku i przykłady).
Na powyższych 2 zrzutach ekranu widać, że wszystkie informacje, które zostały dodane do kolekcji i opisy żądań, są uchwycone w podglądzie dokumentacji w stylu przeceny.
która certyfikacja testowania oprogramowania jest najlepsza
Ponadto dokumentacja domyślnie zawiera podświetlone powiązania językowe, co znacznie ułatwia komuś, kto chce bezpośrednio wykonać żądanie API w wymienionym języku.
# 8) Pozwala również na wykonywanie bardzo podstawowych modyfikacji stylizacji, takich jak zmiana koloru tła, zmiana koloru tła i pierwszego planu szablonów nagłówków itp. Ale ogólnie sam widok domyślny wystarczy do opublikowania naprawdę dobrego zestawu dokumentacji przechwytującej wiele ważne szczegóły dotyczące interfejsu API.
Wniosek
W tym samouczku omówiliśmy obsługę dokumentacji API zapewnianą przez firmę Postman, za pomocą której możemy stworzyć dobrze wyglądającą, stylizowaną dokumentację przy minimalnym wysiłku.
Pozwala również na wiele dobrych szablonów i stylów zdefiniowanych przez użytkownika, które można zastosować do generowanych dokumentów, a także umożliwia publikowanie dokumentacji również pod publicznym adresem URL.
W przypadku prywatnych punktów końcowych interfejsu API istnieje również możliwość publikowania dokumentacji w domenie niestandardowej, którą można skonfigurować dla kont korporacyjnych lub użytkowników.
Dalsza lektura = >> Jak opublikować umowę paktową z brokerem paktowym
=> Odwiedź tutaj, aby nauczyć się listonosza od podstaw.
rekomendowane lektury
- Samouczek POSTMAN: Testowanie API przy użyciu POSTMAN
- Jak i kiedy używać skryptów Postman Pre Request i Post Request?
- Jak używać programu Postman do testowania różnych formatów API?
- Jak korzystać z integracji wiersza poleceń z Newman w Postman?
- Samouczek dotyczący interfejsu API REST: Architektura i ograniczenia interfejsu API REST
- Generuj żywą dokumentację za pomocą pikli dla plików funkcji Specflow
- Automatyzacja walidacji odpowiedzi z asercjami w programie Postman
- Kody odpowiedzi Rest API i rodzaje żądań odpoczynku