Spring Boot Ve Swagger ile REST API Dokümantasyonu – 2

0 2,661

Öncelikle serinin ilk bölümünü okumadıysanız buradan ulaşabilirsiniz.

Bu bölümde birden fazla servisi nasıl dokümante edebilirizi inceleyeceğiz. İlk bölümdeki controller’a ek olarak iki controller daha ekledim. Odak noktamız onlar olmadığı için bu kez onların kodunu eklemeyeceğim.

Servislerinize groupName vererek gruplayabilirsiniz. Paths metoduna parametre olarak verdiğimiz metod içerisinde PathSelectors.any() ile basePackage altında bulunan controller’ı kastetmiş oluyoruz.

Swagger ile servislerimizi dökümante edileceğimiz bazı annotation’lar mevcut. Bunlar ile servis ve method’ları daha açıklayıcı bir hale getirebiliriz. Hatta örnek request input’u oluşturup, geliştirme aşamasında veya daha sonrasında servisin doğru çalışıp çalışmadığını hemen test edebilirsiniz.

Annotations

  • @Api
  • @ApiModel
  • @ApiModelProperties
  • @ApiOperation
  • @ApiParam
  • @ApiResponse

Daha fazla annotation ve bilgiye buradan ulaşabilirsiniz. Bu listedeki en sevdiğim annotation benim için @ApiModelProperties çünkü örnek değerleri servisi yazarken hazırlayabiliyorum ve istersem belirlediğim default değerler ile yazdığım servisi hızlıca test edebiliyorum. Bu işi tabii ki farklı yöntemlerle de yapabilirsiniz fakat happy path’i görmek adına elinizin altında kullanışlı bir yöntem bulunması farklı senaryolarda işinizi kolaylaştırabilir.

Yukarıda kullanıcı kaydı için kullanılabilecek input değeri bulunmaktadır. Sonuç olarak göreceğimiz değerler aşağıdaki gibi olacaktır.

@ApiResponses ile servisten dönen kodları belirtebilirsiniz.  Ayrıca @ApiOperation yardımıyla metodun yaptığı işlemi açıklayabilirsiniz.

Kaynak;

https://github.com/swagger-api/swagger-core/wiki/annotations

https://stackabuse.com/java-rest-api-documentation-with-swagger2/

Faydalı olması dileğiyle.

Email adresiniz yayınlanmayacaktır.