Bir REST API için çevrimiçi dokümantasyonu yapılandırma

Verileri JSON ve XML formatlarına serileştiren ilk Rest API'mi oluşturuyorum. API istemcilere uygulanan uç noktaları seçebilecekleri bir dizin sayfası sağlamak istiyorum.

API'mi en kullanışlı hale getirmek için hangi bilgileri eklemem gerekiyor ve bunu nasıl düzenlemeliyim?

Bu basit bir cevap için çok karmaşık bir soru.

Swagger Specification ( OpenAPI ) gibi mevcut API çerçevelerine ve apiary.io ve apiblueprint.org gibi hizmetlere göz atmak isteyebilirsiniz .

Ayrıca, üç farklı şekilde açıklanan, düzenlenmiş ve hatta şekillendirilmiş aynı REST API'nin bir örneğini burada bulabilirsiniz. Mevcut ortak yollardan öğrenmek sizin için iyi bir başlangıç ​​olabilir.

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

En üst düzeyde, kaliteli REST API belgelerinin en azından aşağıdakileri gerektirdiğini düşünüyorum:

• tüm API uç noktalarınızın listesi (temel / göreli URL'ler)
• her uç nokta için karşılık gelen HTTP GET / POST / ... yöntem türü
• istek / yanıt MIME türü (parametreler nasıl kodlanır ve yanıtlar nasıl ayrıştırılır)
• HTTP başlıkları dahil örnek bir istek / yanıt
• URL, gövde ve başlıklar dahil tüm parametreler için belirtilen tür ve biçim
• kısa bir metin açıklaması ve önemli notlar
• popüler web programlama dillerinde uç noktanın kullanımını gösteren kısa bir kod parçası

Ayrıca, API tanımınızı veya şemanızı ayrıştırabilen ve sizin için uygun bir belge seti oluşturabilen birçok JSON / XML tabanlı belge çerçevesi vardır. Ancak bir belge oluşturma sistemi seçimi, projenize, dilinize, geliştirme ortamınıza ve diğer birçok şeye bağlıdır.