Menü

Postacıda API Belgeleri Nasıl Oluşturulur?

  • Ana
  • Diğer
  • Postacıda API Belgeleri Nasıl Oluşturulur?

how create api documentation postman

Sorunları Ortadan Kaldırmak Için Enstrümanımızı Deneyin

Bu Eğitim, Postacı Aracı Tarafından Sağlanan API Dokümantasyon Desteğini Kullanarak Asgari Çabayla İyi Görünümlü, Tarz Belgelendirmenin Nasıl Oluşturulacağını Açıklar:

İster Dahili ister Halka açık olsun, herhangi bir API için dokümantasyon, başarısının en temel bileşenlerinden biridir.

Bunun başlıca nedeni, dokümantasyonun kullanıcılarınızla iletişim kurma biçiminiz olmasıdır.

  • API'niz nasıl kullanılmalıdır?
  • Tüm durum kodları hangi desteklenir?
  • Hata kodları nelerdir?
  • Tüm Yöntem türleri nelerdir?

Tüm bu bilgiler, herhangi birinin istenen ihtiyaç için API'yi kullanması veya uygulaması için gereklidir.

=> Basit Postacı Eğitimi Serisine Buradan Dikkat Edin.

Postacı - API Belgeleri Oluşturma

youtube'dan video indirmek için yazılımlar

Postman, kullanımı kolay bir dokümantasyon metodolojisi sağlar ve temel dokümantasyon için, Postman koleksiyonu aracılığıyla bir düğmeye tıklamak kadar basittir ve API dokümantasyonunuz için genel URL alabilirsiniz.

Ne öğreneceksin:

Postacıda API Belgeleri Oluşturma

Dokümantasyon Özellikleri

Postacı dokümantasyon oluşturucunun göze çarpan özellikleri şunları içerir:

  • Markdown sözdizimini destekler. Markdown, genellikle herhangi bir Github projesinde fark etmiş olmanız gereken genel dokümantasyon sözdizimidir. Stil ve metin biçimlendirmeyi daha tanıdık ve daha kolay hale getirir.
  • Dokümantasyon oluşturmak için belirli bir sözdizimi / gereksinim yoktur. Talep ve toplama bilgileri, dokümantasyon oluşturmak için en iyi şekilde kullanılır.
  • Genel bir URL'de veya özel bir etki alanında (kurumsal kullanıcılar için) yayınlanabilir.
  • C #, PHP, Ruby, Python, Node vb. Gibi farklı dillerde API'ye çağrı yapmak için kod parçacıkları oluşturur.

Dokümantasyon Oluşturma

Postacı belge oluşturucu; koleksiyon, klasör ve bireysel istek açıklamasına atıfta bulunur ve koleksiyon için belgeler oluştururken veya oluştururken bunları harmanlar.

Başlıklar, Sorgu dizesi parametreleri, Form parametreleri gibi çeşitli istek parametrelerini kullanır ve bu değerlerin istek belgelerinde kullanımını belirtir.

İşte bir Video Eğitimi:

Diğer makalelerimizle aynı test API'sini kullanarak 3 istek içeren temel bir koleksiyon oluşturalım. Koleksiyon açıklamasına ve münferit isteklere bazı bilgiler ekleyeceğiz ve ayrıca dokümantasyon oluşturulurken de kaydedilecek olan bazı örnek talepler ve yanıtlar oluşturacağız.

İsteklerle ilgili temel bilgileri eklemek ve ardından belgeleri oluşturmak için aşağıdaki adımları izleyin.

# 1) 3 istek içeren bir koleksiyon oluşturun, yani Kullanıcı Kaydet, Kullanıcı Giriş Yap ve Kullanıcı Al (Başvur İşte yükler ve API URL'leri istemek için).

#iki) Şimdi koleksiyona markdown formatında bazı bilgiler ekleyelim. Markdown, Github'daki hemen hemen tüm dokümantasyon için kullanılan standart bir formattır (Markdown hakkında daha fazla bilgi için İşte ).

Koleksiyon açıklamasına aşağıdaki gibi indirgeme biçiminde bazı bilgiler ekleyeceğiz.

Markdown formatında koleksiyon açıklaması

İndirimin nasıl göründüğünü önizlemek için açık kaynaklı web portalına bakın İşte.

Markdown Belgeleri

# 3) Şimdi açıklamaları koleksiyondaki bireysel isteklere ekleyeceğiz. Koleksiyona benzer şekilde, indirgeme formatı da talep açıklamaları için desteklenir (Markdown kılavuzu hakkında daha ayrıntılı bilgi için bkz. İşte ).

Kayıt Kullanıcı uç noktası isteklerinden birinin örneğini görelim (Aynısı diğer istekler için de geçerli olabilir).

Markdown Metni:

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

Markdown Önizlemesi:

Markdown Önizlemesi

# 4) Tüm API uç noktaları için, dokümantasyon oluşturucu tarafından kullanılacak bir örneği yakalayalım veya kaydedelim.

Örnek, dikkate alınan API isteği için örnek bir istek yanıtından başka bir şey değildir. Yanıtı örnek olarak kaydetmek, dokümantasyon oluşturucunun dokümantasyonun bir parçası olarak onu yakalamasını sağlar.

Bir örnek kaydetmek için, 'Gönder' düğmesine basarak isteği yerine getirin ve yanıt sekmesinde Yanıtı Kaydet -> Örnek Olarak Kaydet .

Örneği Kaydet

Örnek kaydedildikten sonra, koleksiyonda kalıcı hale gelir ve gelecekte herhangi bir zamanda bir Örnekler bağlantı istek oluşturucudaki.

# 5) Yukarıdaki tüm bilgiler eklendikten sonra, bir dokümantasyon önizlemesinin nasıl oluşturulacağını görelim.

Koleksiyon seçeneklerini açın ve ' Belgeleri Yayınla ”.

Belgeleri Yayınla

Not: Burada dikkat edilmesi gereken önemli bir nokta, yalnızca Postman ile kayıtlı kullanıcıların Postacı'da Dokümanları yayınla özelliğini kullanabileceğidir. Kayıt ücretsizdir ancak e-posta hesabınız üzerinden yapılması gerekir. Kayıtlı hesaplara eklenen koleksiyonları ve çalışma alanlarını paylaşmak, monitörler oluşturmak gibi başka yetenekler / özellikler vardır.

# 6) Bir Zamanlar ' Belgeleri Yayınla 'Yürütüldüğünde, Postman koleksiyonu ayrıntılarını içeren bir tarayıcı sekmesi açılır (Postman bu koleksiyonu dahili olarak kendi sunucularında ve kullanıcının yerel dosya sistemine ek olarak barındırır).

Belge Toplama

Tıklamak 'Ön izleme' Belgeleri yayınlanmadan önce görüntülemek için.

' Koleksiyonu Yayınla ”Bağlantısı, dokümanları herkesin erişebileceği bir URL'de yayınlayacaktır. Genel URL'de yayınlamak için hassas yetkilendirme bilgilerine sahip API'lerin yayınlanması genellikle önerilmez. Bu tür API'ler, Postman'ın kurumsal hesaplarıyla özel etki alanları kullanılarak yayınlanabilir.

# 7) Doküman önizlemesinin nasıl göründüğüne bakalım. ' Belgeleri Önizle ', Belgeleri Postacı'nın sunucularında barındırılan bir önizleme modunda açar. Belgelerde hangi farklı ayrıntıların yakalandığını görelim (Farklı yerlerde yapılandırdığımız gibi. Örneğin , koleksiyon açıklaması, talep açıklaması ve örnekler).

Postacı Dokümantasyon Örneği

Markdown

Yukarıdaki 2 ekran görüntüsünde, koleksiyona eklenen tüm bilgilerin ve talep açıklamalarının dokümantasyon önizlemesinde markdown tarzı bir şekilde yakalandığını görebilirsiniz.

ücretsiz çevrimiçi anime nasıl izlenir

Ayrıca, dokümantasyon varsayılan olarak vurgulandığı şekilde dil bağlamaları sağlar ve bu, API isteğini doğrudan listelenen dilde yapmak isteyen biri için çok daha kolay hale getirir.

# 8) Ayrıca, arka plan rengini değiştirme, başlık şablonlarının arka planını ve ön plan rengini değiştirme vb. Gibi çok temel stil değişikliklerini gerçekleştirmenize de olanak tanır. Ancak genel olarak, varsayılan görünümün kendisi, birçok şeyi yakalayan gerçekten iyi bir belge seti yayınlamak için yeterlidir. API ile ilgili önemli ayrıntılar.

Sonuç

Bu eğitici yazıda, Postman tarafından sağlanan API dokümantasyon desteğini gözden geçirdik ve bunu kullanarak, asgari çabayla iyi görünümlü, şekillendirilmiş bir dokümantasyon oluşturabiliriz.

Ayrıca, oluşturulan dokümanlara uygulanabilecek birçok iyi şablona ve kullanıcı tanımlı stillere izin verir ve dokümantasyonun genel bir URL'de yayınlanmasına da olanak tanır.

Özel API uç noktaları için, kurumsal hesaplar veya kullanıcılar için yapılandırılabilen özel bir etki alanına belge yayınlamak için bir hüküm de vardır.

Daha fazla okuma = >> Pact Broker'a Pact Sözleşmesi nasıl yayınlanır

=> Postacıyı Sıfırdan Öğrenmek İçin Burayı Ziyaret Edin.

Önerilen Kaynaklar

^