Spring Boot Swagger UI nedir?

Swagger Rest API geliştirmek için gerekli bir sözleşme standardı ve bu çerçevede işlev gören yardımcı araçlar sunan bir teknolojidir. Swagger sunduğu standart ve araçlarla API tasarım, geliştirme, dokümantasyon ve test aşamasında kolaylık sağlamaktadır.

Swagger OpenAPI standardını kullanarak, API’lerimizi hem insanların hem de makinelerin anlayacağı formatta ortak bir dilde paylaşabiliriz. İnsanlar Open API sözleşmelerinize bakınca servis içeriğinin ne olduğunu anlayabilir. Bunun yanında makineler için sözleşme kurallarına uyan client veya server kodu üretebiliriz. 40 üzeri dil ve uygulama platformunu destekleyen Swagger, günümüz API geliştiriminde iyi bir platform tercihi olarak karşımıza çıkmaktadır.

API geliştirmede diğer bir önemli ihtiyaç ise dokümantasyon ihtiyacıdır. Servislerinizi diğer geliştiricilere özel veya herkese açık olarak paylaştığınızda, API metotlarının ne iş gördüğü ve nasıl çalıştığı ile ilgili anlaşılır bir dokümanınız olmalıdır. API dokümanlarını el emeğiyle yazmak hem zor hem de güncel tutması imkansızdır. Bir biçimde bu dokümanların otomatik olarak üretilmesi gerekir. Swagger’in diğer bir özelliği YAML veya JSON biçiminde tutulan servis sözleşmelerinden otomatik olarak dokümantasyon oluşturabiliyor olmasıdır.

Öncelikle projede swagger kullanmak için aşağıdaki resimdeki bağımlılıkları eklememiz gerekmektedir.(pom.xml)

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

Sonrasıda aşağıdaki gibi bir konfigürasyon dosyamızı oluşturacağız.

@Configuration
@EnableSwagger2
public class SwaggerConfig
{
@Bean
    public Docket api(){
    return new Docket(DocumentationType.SWAGGER_2).select()
            .apis(RequestHandlerSelectors.basePackage("com.kodlayalim))//projenin dizini
            .paths(PathSelectors.regex("/.*"))
                    .build().apiInfo(apiEndPointsInfo());
}
    private ApiInfo apiEndPointsInfo(){
    return new ApiInfoBuilder().title("Spring Boot Swagger Örneği")
            .description("Pet Api Dökümantasyonu")
            .contact(new Contact("Haydi Kodlayalim","",""))
            .license("Apache 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .version("1.12.3")
            .build();
    }

}

@Api - Rest Controller dokümantasyonu.

@Api(value = "Benim Pet API dökümentasyonum")
public class PetController 
{
}

@ApiModel - Rest API Model dokümantasyonu

@ApiModel(value = "Benim pet nesnem",description = "Benim Pet")
public class Pet 
{
}

@ApiModelProperty - Model property dokümantasyonu

 @ApiModelProperty("Pet nesnesinin tekil Id alanı")
    private int id;
    @ApiModelProperty("Pet nesnesinin tekil adi alanı")
    private String name;
    @ApiModelProperty("Pet nesnesinin tekil Tarih alanı")
    private Date date;

@ApiOperation - Rest method dokümantasyonu

@ApiOperation(value = "Yeni Pet ekleme metodum",notes = "Bu metodu dikkatli kullan")
    public ResponseEntity<Pet> kaydet(@RequestBody @ApiParam(value = "hayvan") Pet pet)
    {
        petList.add(pet);
        return ResponseEntity.ok(pet);
    }

@ApiParam - Method parametresi dokümantasyonu

@ApiResponse - Method Response nesnesi icin dokümantasyonu