Gerçek programlamaya başlamadan önce arayüzleri tamamen tanımlamanın avantajları vardır: Bir yandan, API öncelikli yaklaşımla geliştiriciler, dokümantasyon için API'nin %100 doğru tanımını elde eder; bu, kod öncelikli yaklaşımla elde edilemez.
Duyuru
(Resim:
Oliver Cam
)
Oliver Glas, Zürih'te tam yığın geliştirici olarak çalışıyor. C64'te programlamaya başladı. Profesyonel olarak Go ve Python da dahil olmak üzere çeşitli dillerde web hizmetleri geliştirmeye odaklanmaktadır. Odak noktası arka uçta Java ve ön uçta TypeScript'tir. Birkaç yıldır OpenAPI temasını keşfediyorum. Açık kaynak alanına dahil olmak ve zaman zaman konferanslar veya çalıştaylar düzenlemek için iyi bir fırsat.
Öte yandan API First, bir BT projesinin güvenilirliğine ve etkinliğine önemli katkı sağlayabilecek geniş bir araç yelpazesinin önünü açıyor. Web hizmetinin tüm yaşam döngüsü boyunca sağladığı diğer faydalar, yalnızca onunla tutarlı bir şekilde çalıştığınız takdirde ortaya çıkar. API First, harici müşteri projeleri için her zaman bir artıdır.
Bu makale, API First'ü OpenAPI 3 (OAS3) ile Maven ile Spring Boot 3 uygulaması olarak bir web hizmetinin geliştirme döngülerine entegre etme hakkındadır. Ayrıca, tam kişiselleştirme talimatlarını içeren parametrelerin açıklamaları da bulunmaktadır. İlgilenenler kılavuzda API First konusuna kısa bir giriş bulabilirler: OpenAPI belgelerinden API program kodu oluşturma.
Spring Boot projesinde API-First
Burada gösterilen örneğin önkoşulu, Java SDK 17 ve Maven içeren bir Spring Boot geliştirme ortamıdır. Uygun ayarlamalarla örnek Gradle ve Spring Boot 2 ile de çalışacaktır ancak Spring Boot 3 için Java 17 şarttır. IntelliJ veya Eclipse gibi bir geliştirme ortamı çok kullanışlıdır. Örnek kod şununla kullanılabilir: git clone Git deposundan gelir ve Swagger Editor'daki oluşturucunun sert çatalı olan Spring Boot için OpenAPI Generator'ı kullanır.
Çatal, Swagger'ı işleten şirket Smartbear'ın birkaç yıldır OAS3'ü mevcut sürüme güncellemeyi reddetmesi nedeniyle oluşturuldu. Swagger daha sonra eski kaynak kodunu oluşturur ve Ocak 2024 itibarıyla uygulamanın Java 1.7 ile Spring Boot 2 sürümünü üretmeye devam eder.
BetterCode() API çevrimiçi konferansı, on iki konuşma ve arayüz kavramları, taslak hazırlama, tasarım, test etme ve bakım konularında iki ek atölye çalışmasıyla API'ler konusuna çok yönlü bir bakış sunuyor. Bazı konuşmacılar pratik örnekler sunacak ve 4 ve 6 Haziran'daki katılımcı ve uygulamalı atölye çalışmaları API düşüncesine ve tüketici odaklı sözleşme testlerine adanacak.
Programın öne çıkanları şöyle:
Ancak açık kaynak topluluğu, çatallı OpenAPI oluşturucuyu aktif olarak sürdürüyor ve yeni diller veya çerçeveler için sürekli olarak yeni jeneratörler piyasaya sürülüyor. Topluluk, bildirilen hataları hızlı bir şekilde düzeltir ve düzenli olarak yeni özellikler uygular. Bununla birlikte, OpenAPI'yi düzenlemek için güncel olmayan oluşturucu olmadan Swagger Düzenleyicinin kendisi şiddetle tavsiye edilir.
Örnekte, yine orijinal olarak Smartbear'dan gelen, OpenAPI belgesi olarak olağan Petstore kullanılıyor. Örnek değerleri içerecek ve XML yerine yalnızca JSON içerecek şekilde özelleştirilmiştir.
Projenin amacı, otomatik olarak %100 doğru API belgelerine ulaşmak için API First'ü Spring Boot yaşam döngüsüne sıkı bir şekilde entegre etmektir. Code First ile belgeleri otomatik olarak oluşturmak da mümkündür (Springdoc anahtar sözcüğü), ancak Springdoc ve diğer kitaplıkların API'leri %100 doğru şekilde yorumlamama riski yüksektir. Bu özellikle yanlış anlamalara yol açabilecek rota parametreleriyle ilgilidir. Kesin dokümantasyon, yalnızca yazılım mimarlarının önce API'yi tanımlaması ve ardından kaynak kodunda standartlaştırılmış bir formda teknik olarak tanımlanmış bağımlılıklar olarak arayüzler ve modeller oluşturmasıyla elde edilir.
API öncelikli yaklaşım şu süreci içerir: Geliştiriciler önce OpenAPI belgesinde değişiklik yapar. Derleme işlemi otomatik olarak karşılık gelen Java arayüzlerini ve şablonlarını oluşturur. API henüz tam olarak uygulanmamışsa veya kodda yanlış uygulanmışsa derleme işleminin başarısız olduğu söylenir.
Yaml veya JSON'daki OpenAPI belgesi, oluşturucunun her iki formatı da anlaması sayesinde geliştirmenin merkezi bir parçası haline gelir. Hem arka uç hem de ön uç için kullanılabilir. Bir monorepoda ön uç ve arka uç aynı belgeyi paylaşır. Bu size gerçeğin tek bir kaynağını verir.
Terminolojiyle ilgili olarak OAS3 spesifikasyonu ile OAS3 belgesi arasında bir ayrım yapılmalıdır. Spesifikasyon OAS3 standardını anlatırken API'nin somut tanımı OAS3 belgesidir. Örneğimizde buna openapi.yaml denir, ancak ad serbestçe seçilebilir.
Özetle Spring Boot projesi aşağıdaki özelliklere sahiptir:
API First'te geliştiriciler, kodlamaya başlamadan önce ilk olarak bir arayüzün yapısını tasarlarlar.
(Resim: Oliver Glas)
API-First projesinin Code First'e göre avantajı: Nihai dokümantasyonun otomatik ve hassas bir şekilde oluşturulmasıdır.
(Resim: Oliver Glas)
API projenin başlangıcındadır
İlk adımda belgenin hazır olmasına gerek olmamasına rağmen API ilk olarak tasarlanmıştır. Ancak yinelenen bir geliştirme döngüsünün ayrılmaz bir parçası olmaya devam ediyor. Geliştiriciler yeni gereksinimleri önce kodda uygulamazlar, bunun yerine bunları OAS3 belgesine (burada: openapi.yaml) yerleştirirler. Oluşturulan arayüzler ve modeller her zaman OAS3 belgelerinin tam bir temsilini oluşturur.
Örnek proje, Petstore örneği olarak indirilen mevcut bir belgeyi kullanıyor. İlk geliştirme döngüsünden önce taslak belgeden bir taslak oluşturmak mümkündür: arkasında henüz herhangi bir iş mantığı olmayan ilk işlevsel uygulama.
Bir saplamanın kullanımı
OpenAPI belgeleri tarafından oluşturulan saplama, gerçek uygulamanın geliştirileceği bir şablon (start.spring.io yerine) görevi görür. Start.spring.io'ya göre avantajı, tüm tanımlanmış API'lerin, OAS3 belgelerinin otomatik olarak oluşturulmasına yönelik ek açıklamaların ve OpenAPI oluşturucu için Maven eklentisinin baştan itibaren pom.xml'ye eklenmesidir. Eklenti, saplama için kullanılan jar dosyası oluşturucunun aynısını içerir.
API First daha sonra geliştirme sürecine entegre edildiğinde, API her değiştirildiğinde kod yeniden oluşturulur; saplamadan farklı olarak yalnızca arayüzler ve modeller oluşturulur.
Saplama ayrıca API'yi tasarladıktan sonra uygulamayı doğrudan test edebilme avantajını da sunar (sola kaydırma). Maven eklentisi, openapi.yaml'daki API'yi değiştirmek, denetleyici arayüzlerinin artık doğru şekilde uygulanmadığı ve derleme hatasına yol açacağı anlamına gelecek şekilde ayarlanmıştır. Bu, API'de önemli değişiklikler yapıldığında geliştiricilerin de kodu buna göre uyarlamaları gerektiğini garanti eder. Eklenti tarafından oluşturulan kod, varsayılan olarak hedef derleme dizininde bulunabilir ve hedef Git deposunda saklanmadığı için orada güvenlidir. Aksi takdirde, her derleme, yalnızca oluşturma tarihi değişmiş olsa bile, oluşturulan tüm dosyaların yeniden arşivlenmesiyle sonuçlanacaktır. Gerekirse yol parametreyle de belirtilebilir. <output> Maven eklentisinde ayarlanabilir.
Saplamayı oluştur
Bu teorik genel bakışın ardından şimdi pratik kısım olan API dokümanı ve taslak ile başlıyoruz. Örnek projeyi GitHub'dan klonladıktan sonra hazırlık dosyaları aynı isimli hazırlık alt dizininde bulunur. İki kontrol dosyası (Linux için .sh, Windows için .ps1) oluşturucuyu ve OpenAPI belgesini (Petstore) indirir. Senaryo generate.* saplamayı oluşturun. Oluşturma sırasında komut dosyasındaki seçenekleri tanımlayın -i.* giriş dosyası (openapi.yaml), -g.* jeneratörün adı (spring) VE -o.* çıkış dizini. Saplamaya gitmelisin -additional-properties.* Java paket adları gibi ek parametreleri tanımlayın (komut dosyasındaki 3-8. satırlar). Saplamanın oluşturulduktan hemen sonra çalıştırılabilir olması için, skipDefaultInterface=false.* aksi halde derlemek için öncelikle arayüz yöntemlerinin denetleyicide uygulanması gerekir.
İşte en önemli parametrelerin açıklaması:
Örnek depoda, düzenlenecek taslak uygulama alt dizininde (Monorepo Stili) bulunur. Uygun bir API öncelikli uygulamaya ulaşmak için hala bazı ayarlamalara ihtiyaç vardır. Daha sonra gerçek uygulama bu taslaktan daha da geliştirilir.
Haberin Sonu
Duyuru
(Resim:
Oliver Cam
)
Oliver Glas, Zürih'te tam yığın geliştirici olarak çalışıyor. C64'te programlamaya başladı. Profesyonel olarak Go ve Python da dahil olmak üzere çeşitli dillerde web hizmetleri geliştirmeye odaklanmaktadır. Odak noktası arka uçta Java ve ön uçta TypeScript'tir. Birkaç yıldır OpenAPI temasını keşfediyorum. Açık kaynak alanına dahil olmak ve zaman zaman konferanslar veya çalıştaylar düzenlemek için iyi bir fırsat.
Öte yandan API First, bir BT projesinin güvenilirliğine ve etkinliğine önemli katkı sağlayabilecek geniş bir araç yelpazesinin önünü açıyor. Web hizmetinin tüm yaşam döngüsü boyunca sağladığı diğer faydalar, yalnızca onunla tutarlı bir şekilde çalıştığınız takdirde ortaya çıkar. API First, harici müşteri projeleri için her zaman bir artıdır.
Bu makale, API First'ü OpenAPI 3 (OAS3) ile Maven ile Spring Boot 3 uygulaması olarak bir web hizmetinin geliştirme döngülerine entegre etme hakkındadır. Ayrıca, tam kişiselleştirme talimatlarını içeren parametrelerin açıklamaları da bulunmaktadır. İlgilenenler kılavuzda API First konusuna kısa bir giriş bulabilirler: OpenAPI belgelerinden API program kodu oluşturma.
Spring Boot projesinde API-First
Burada gösterilen örneğin önkoşulu, Java SDK 17 ve Maven içeren bir Spring Boot geliştirme ortamıdır. Uygun ayarlamalarla örnek Gradle ve Spring Boot 2 ile de çalışacaktır ancak Spring Boot 3 için Java 17 şarttır. IntelliJ veya Eclipse gibi bir geliştirme ortamı çok kullanışlıdır. Örnek kod şununla kullanılabilir: git clone Git deposundan gelir ve Swagger Editor'daki oluşturucunun sert çatalı olan Spring Boot için OpenAPI Generator'ı kullanır.
Çatal, Swagger'ı işleten şirket Smartbear'ın birkaç yıldır OAS3'ü mevcut sürüme güncellemeyi reddetmesi nedeniyle oluşturuldu. Swagger daha sonra eski kaynak kodunu oluşturur ve Ocak 2024 itibarıyla uygulamanın Java 1.7 ile Spring Boot 2 sürümünü üretmeye devam eder.
BetterCode() API çevrimiçi konferansı, on iki konuşma ve arayüz kavramları, taslak hazırlama, tasarım, test etme ve bakım konularında iki ek atölye çalışmasıyla API'ler konusuna çok yönlü bir bakış sunuyor. Bazı konuşmacılar pratik örnekler sunacak ve 4 ve 6 Haziran'daki katılımcı ve uygulamalı atölye çalışmaları API düşüncesine ve tüketici odaklı sözleşme testlerine adanacak.
Programın öne çıkanları şöyle:
Ancak açık kaynak topluluğu, çatallı OpenAPI oluşturucuyu aktif olarak sürdürüyor ve yeni diller veya çerçeveler için sürekli olarak yeni jeneratörler piyasaya sürülüyor. Topluluk, bildirilen hataları hızlı bir şekilde düzeltir ve düzenli olarak yeni özellikler uygular. Bununla birlikte, OpenAPI'yi düzenlemek için güncel olmayan oluşturucu olmadan Swagger Düzenleyicinin kendisi şiddetle tavsiye edilir.
Örnekte, yine orijinal olarak Smartbear'dan gelen, OpenAPI belgesi olarak olağan Petstore kullanılıyor. Örnek değerleri içerecek ve XML yerine yalnızca JSON içerecek şekilde özelleştirilmiştir.
Projenin amacı, otomatik olarak %100 doğru API belgelerine ulaşmak için API First'ü Spring Boot yaşam döngüsüne sıkı bir şekilde entegre etmektir. Code First ile belgeleri otomatik olarak oluşturmak da mümkündür (Springdoc anahtar sözcüğü), ancak Springdoc ve diğer kitaplıkların API'leri %100 doğru şekilde yorumlamama riski yüksektir. Bu özellikle yanlış anlamalara yol açabilecek rota parametreleriyle ilgilidir. Kesin dokümantasyon, yalnızca yazılım mimarlarının önce API'yi tanımlaması ve ardından kaynak kodunda standartlaştırılmış bir formda teknik olarak tanımlanmış bağımlılıklar olarak arayüzler ve modeller oluşturmasıyla elde edilir.
API öncelikli yaklaşım şu süreci içerir: Geliştiriciler önce OpenAPI belgesinde değişiklik yapar. Derleme işlemi otomatik olarak karşılık gelen Java arayüzlerini ve şablonlarını oluşturur. API henüz tam olarak uygulanmamışsa veya kodda yanlış uygulanmışsa derleme işleminin başarısız olduğu söylenir.
Yaml veya JSON'daki OpenAPI belgesi, oluşturucunun her iki formatı da anlaması sayesinde geliştirmenin merkezi bir parçası haline gelir. Hem arka uç hem de ön uç için kullanılabilir. Bir monorepoda ön uç ve arka uç aynı belgeyi paylaşır. Bu size gerçeğin tek bir kaynağını verir.
Terminolojiyle ilgili olarak OAS3 spesifikasyonu ile OAS3 belgesi arasında bir ayrım yapılmalıdır. Spesifikasyon OAS3 standardını anlatırken API'nin somut tanımı OAS3 belgesidir. Örneğimizde buna openapi.yaml denir, ancak ad serbestçe seçilebilir.
Özetle Spring Boot projesi aşağıdaki özelliklere sahiptir:
- API'ye yönelik ayarlamalar OpenAPI belgesinde (OAS3, openapi.yaml) yapılır.
- Derleme, bir Maven eklentisi kullanarak OAS3 belgesinden Java modelleri ve arayüzleri oluşturur.
- Springdoc, derleme sırasında otomatik olarak API belgeleri oluşturur.
- API'nin değiştirilmesi, uygun şekilde değiştirilene kadar uygulama kodunda beklenen bir hataya neden olacaktır.
- API'ler, uygulama olmasa bile statik örnek değerlerle (200 yerine durum kodu 501) anında yanıt verir.
- API'lere anında erişilebildiği için anında test edilebilirler (sola kaydırma testi).
API First'te geliştiriciler, kodlamaya başlamadan önce ilk olarak bir arayüzün yapısını tasarlarlar.
(Resim: Oliver Glas)
API-First projesinin Code First'e göre avantajı: Nihai dokümantasyonun otomatik ve hassas bir şekilde oluşturulmasıdır.
(Resim: Oliver Glas)
API projenin başlangıcındadır
İlk adımda belgenin hazır olmasına gerek olmamasına rağmen API ilk olarak tasarlanmıştır. Ancak yinelenen bir geliştirme döngüsünün ayrılmaz bir parçası olmaya devam ediyor. Geliştiriciler yeni gereksinimleri önce kodda uygulamazlar, bunun yerine bunları OAS3 belgesine (burada: openapi.yaml) yerleştirirler. Oluşturulan arayüzler ve modeller her zaman OAS3 belgelerinin tam bir temsilini oluşturur.
Örnek proje, Petstore örneği olarak indirilen mevcut bir belgeyi kullanıyor. İlk geliştirme döngüsünden önce taslak belgeden bir taslak oluşturmak mümkündür: arkasında henüz herhangi bir iş mantığı olmayan ilk işlevsel uygulama.
Bir saplamanın kullanımı
OpenAPI belgeleri tarafından oluşturulan saplama, gerçek uygulamanın geliştirileceği bir şablon (start.spring.io yerine) görevi görür. Start.spring.io'ya göre avantajı, tüm tanımlanmış API'lerin, OAS3 belgelerinin otomatik olarak oluşturulmasına yönelik ek açıklamaların ve OpenAPI oluşturucu için Maven eklentisinin baştan itibaren pom.xml'ye eklenmesidir. Eklenti, saplama için kullanılan jar dosyası oluşturucunun aynısını içerir.
API First daha sonra geliştirme sürecine entegre edildiğinde, API her değiştirildiğinde kod yeniden oluşturulur; saplamadan farklı olarak yalnızca arayüzler ve modeller oluşturulur.
Saplama ayrıca API'yi tasarladıktan sonra uygulamayı doğrudan test edebilme avantajını da sunar (sola kaydırma). Maven eklentisi, openapi.yaml'daki API'yi değiştirmek, denetleyici arayüzlerinin artık doğru şekilde uygulanmadığı ve derleme hatasına yol açacağı anlamına gelecek şekilde ayarlanmıştır. Bu, API'de önemli değişiklikler yapıldığında geliştiricilerin de kodu buna göre uyarlamaları gerektiğini garanti eder. Eklenti tarafından oluşturulan kod, varsayılan olarak hedef derleme dizininde bulunabilir ve hedef Git deposunda saklanmadığı için orada güvenlidir. Aksi takdirde, her derleme, yalnızca oluşturma tarihi değişmiş olsa bile, oluşturulan tüm dosyaların yeniden arşivlenmesiyle sonuçlanacaktır. Gerekirse yol parametreyle de belirtilebilir. <output> Maven eklentisinde ayarlanabilir.
Saplamayı oluştur
Bu teorik genel bakışın ardından şimdi pratik kısım olan API dokümanı ve taslak ile başlıyoruz. Örnek projeyi GitHub'dan klonladıktan sonra hazırlık dosyaları aynı isimli hazırlık alt dizininde bulunur. İki kontrol dosyası (Linux için .sh, Windows için .ps1) oluşturucuyu ve OpenAPI belgesini (Petstore) indirir. Senaryo generate.* saplamayı oluşturun. Oluşturma sırasında komut dosyasındaki seçenekleri tanımlayın -i.* giriş dosyası (openapi.yaml), -g.* jeneratörün adı (spring) VE -o.* çıkış dizini. Saplamaya gitmelisin -additional-properties.* Java paket adları gibi ek parametreleri tanımlayın (komut dosyasındaki 3-8. satırlar). Saplamanın oluşturulduktan hemen sonra çalıştırılabilir olması için, skipDefaultInterface=false.* aksi halde derlemek için öncelikle arayüz yöntemlerinin denetleyicide uygulanması gerekir.
İşte en önemli parametrelerin açıklaması:
- useSpringBoot3=true Spring Boot sürümü 2.7 yerine 3.1.3
- apiFirst=doğru Anahtar, API First'ü ayarlar ve OpenAPI Generator'daki Maven eklentisini pom.xml dosyasına ekler. Bu, şablonlar ve arayüzler gibi standart kodların her yapıda yeniden oluşturulabileceği anlamına gelir. Hazırlık/bin/petstore_spring_apifirst/target/geneered-sources/openapi/src/main/Java dizinini sınıf yolunuza veya IntelliJ'e eklemeniz gerekebilir: Generated Sources Root işaret.
- skipDefaultInterface=yanlış Bu varsayılan değer, API isteklerine zaten statik örnek değerlerle yanıt veren varsayılan Java arayüzlerini oluşturur. Bunlar sonraki geliştirme sırasında denetleyiciye dahil edilecektir. @Override üzerine yazılmış. Bunun avantajı, uygulamanın anında derlenip çalıştırılabilmesi ve sonraki denetleyici tarafından arayüzlerin yöntem imzalarının üzerine ayrı ayrı yazılabilmesidir.
- returnSuccessCode=yanlış Bu ayar test açısından ilginçtir: varsayılan Java arayüzleri, 501 “Uygulanmadı” HTTP durum koduyla yanıt verir. sen de gelebilirsin returnSuccessCode=true Uygulamanın HTTP kodu 200 ile yanıt vererek saplamayı test için uygun hale getireceğini belirtin.
Örnek depoda, düzenlenecek taslak uygulama alt dizininde (Monorepo Stili) bulunur. Uygun bir API öncelikli uygulamaya ulaşmak için hala bazı ayarlamalara ihtiyaç vardır. Daha sonra gerçek uygulama bu taslaktan daha da geliştirilir.
Haberin Sonu