API Dokümantasyonun Standartlaştırılması
Durum: Geliştirme için seçildi
Tarih: 2022-12-14
Teklif Eden: Architect Team
Karar Alıcılar: Architect Team
Süpervizör: Kerim Kaan Dönmez
Danışılanlar: CTO, PMs
Bilgilendirilenler: Tech Team
Bağlam and Problem Tanımı
BiSU backend servislerinin dokümantasyon ve test amaçlı olarak tek bir noktada toplanması gerekmektedir. Uygulama servislerinden, cockpit servislerine, Trendyol servislerine kadar geniş bir yelpazede servisler bulunmaktadır. Bu servislerin, servislerin kullanılabilmesi için gerekli olan bilgilerin tek bir noktada toplanması, servislerin acil bir durumda kullanılabilmesi ve servislerin test edilmesi için gereklidir.
Etkilenenler
- Tech Team
Olası Çözüm Önerileri
Seçenek-1: Postman koleksiyonunun toplanması
Postman üzerinde tüm servislerin domain bazlı olarak toplanması ve environment değerlerinin değiştirilerek servislerin test edilmesi sağlanabilir.
Seçenek-2: Swagger koleksiyonunun toplanması
Swagger üzerinde tüm servislerin domain bazlı olarak toplanması ve test edilebilir hale getirilmesi sağlanabilir.
Seçenek-3: JSDoc ile servislerin dokümante edilmesi
Tüm servislerin JSDoc ile dokümante edilmesi ve bu dokümantasyonun bir arada toplanması sağlanabilir. JSDoc ile dokümante edilen servislerin ekipçe kullanılabilmesi için bu JSDoc'ların HTML'e dönüştürülmesi gerekmektedir.
Karar Verilen Çözüm Yolu
- Seçenek-1
Alınan Kararın Eksi ve Artıları
Artılar
- Postman genel olarak kabul görmüş bir araç olarak kullanılmaktadır. Bu sebeple dokümantasyonun Postman üzerinde toplanması, servislerin test edilmesi ve servislerin kullanılması için gerekli olan bilgilerin tek bir noktada toplanması ile acil durumlarda yönetimi kolaylaştıracaktır.
- Ekipçe bir servisten faydalanmak isteyen kişilerin Postman üzerinde servisi deneyerek kullanımı servisten ne tür cevaplar dönüyor, servis ne tür parametreler alıyor gibi bilgileri öğrenmesi kolaylaşacaktır.
Eksiler
- Servis sayısının fazlalığı ve domainlere ayrılması gerektiğinden bu koleksiyonun toplanması zaman alacaktır.
- Bazı servisler için VPN veya Whitelist gerekliliğinden bu servislerin test edilmesi tüm ekibe sağlanamayacaktır.
Validasyon
- Route deklarasyonlarına Postman'deki konumu yazılabilir.
Ek Notlar
...