Teknik işi kod ve alan tablolarıyla açıklayın
Bir uç noktanın açıklamasını, istek örneğini ve yanıtını tasarım görüşmesinin yanında tutun. API Documentation, HTTP ve JSON örnekleri için düzenlenebilir metin ve Code block nesneleriyle başlar. Örnek sözleşmeyi uyarlayın, karşılaştırma gerektiğinde alan tablosu ekleyin ve kod parçalarını okunabilir tutun. Tuval, arayüz değiştikçe görsel incelenebilen ve düzenlenmeye devam edilen teknik referansa dönüşür.
Canvas → Templates → API Documentation → Code block → Code languageNeler öğreneceksiniz?
- Yerel kod bloklarını düzenleyip gösterim dilini seçin.
- İstek, başarı ve hata örneklerini tutarlı tutun.
- Alan gereksinimlerini düzenlenebilir ızgarada karşılaştırın.
Boilerrum’da örnek bir projeden alındı. Uygulama arayüzü İngilizce gösterilmektedir.
Bu rehberde
01
Uç nokta referansıyla başlayın
Templates içinde API Documentation arayıp Use template seçin. Request, Response / 201 Created, Request fields ve Error / 400 Bad Request bölümlerini inceleyin. Başlığı, uç noktayı ve açıklamaları görüşeceğiniz sözleşmeyle değiştirin. api.example.com adresi ve görev verileri örnektir; tahtayı referans olarak kullanmadan önce bunları gözden geçirin.
02
İstek kodunu düzenleyin
İstek Code block nesnesini seçip kod önizlemesine çift tıklayın veya seçili bloğa odaklanıp Enter ya da F2 kullanın. Code content alanında istek metnini girin. Başlıktaki Code language ile HTTP, JSON veya uygun başka dili seçin. Escape ile önizlemeye dönüp içeriğin ve dilin bu bloğa ait olduğunu kontrol edin.
03
Başarıyı ve hatayı birlikte açıklayın
Yanıt ve hata bloklarını ayrı düzenleyin; her örnekte Code language seçimini uygun tutun. Alan adlarını, kimlikleri ve durum ifadelerini istek açıklamasıyla eşleştirin. Çağıranın sonraki adımını anlatmak için hatanın yanına kısa cümle ekleyin. Bunlar incelenecek belge örnekleridir; doğruluklarını ekibinizin sürdürdüğü sözleşmeyle karşılaştırın.
04
Alan gereksinimlerini karşılaştırın
Kısa bir karşılaştırma için Grid tools açıp dört satır ve dört sütunlu ızgara seçin. Hücrelere çift tıklayarak başlığa Field, Type, Required ve Meaning yazın; altına üç istek alanını açıklayın. Izgarayı kodun yanına koyup adları kod parçalarıyla karşılaştırın. Şablondaki mevcut metin satırlarını yalnızca yararlı açıklama ekledikleri yerde tutun.
05
Referansı kontrol edip kullanılabilir tutun
Kod düzenleme kipinden çıkıp Fit view ile tüm referansı inceleyin. Uzun satırları, küçük tablo metnini ve başarı ile hata örneklerinin alan açıklamalarıyla uyumunu kontrol edin. Tuvali kaydedin. Değerlendirme çıktısı için çerçeve ekleyip Present → Frame options üzerinden aktarın; düzenlenebilir blokları tahtada tutarken indirilen görseli kontrol edin.
Tuvaliniz, okunabilir alan karşılaştırmasıyla birlikte tutarlı istek, yanıt ve hata örnekleri üzerinden uç noktayı açıklar. Ekip sözleşmeyi görsel inceleyip özgün teknik malzemeyi yerinde düzenleyebilir.