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

By Cem Dırman Last updated Jul 25, 2020

Ö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.



@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2).groupName("Tüm Servisler").select()
				.apis(RequestHandlerSelectors.basePackage("com.bilisimio.controller")).paths(allPaths()).build()
				.apiInfo((apiInfo()));
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("REST API").description("REST API Documentation")
				.termsOfServiceUrl("https://bilisim.io").license("Bilisimio License").licenseUrl("cem@bilisim.io")
				.version("1.0").build();
	}

	private Predicate<String> allPaths() {
		return PathSelectors.any();
	}
}

@Configuration

@EnableSwagger2

public class SwaggerConfig {

@Bean

public Docket api() {

return new Docket(DocumentationType.SWAGGER_2).groupName("Tüm Servisler").select()

.apis(RequestHandlerSelectors.basePackage("com.bilisimio.controller")).paths(allPaths()).build()

.apiInfo((apiInfo()));

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder().title("REST API").description("REST API Documentation")

.termsOfServiceUrl("https://bilisim.io").license("Bilisimio License").licenseUrl("[email protected]")

.version("1.0").build();

}

private Predicate<String> allPaths() {

return PathSelectors.any();

}

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.



public class UserRequest {

	@ApiModelProperty(example = "cem")
	private String     firstName;
	@ApiModelProperty(example = "dirman")
	private String     lastName;
	@ApiModelProperty(example = "cemdrman@gmail.com")
	private String     email;
	@ApiModelProperty(example = "password")
	private String     password;
	@ApiModelProperty(notes = "0 gönderilmeyecektir",example = "5394176264")
	private String     phone;
	private GenderType gender;
	@ApiModelProperty(notes = "url girilmelidir", example = "https://bilisim.io")
	private String     profileImage;
	@ApiModelProperty(example = "bilgisayar mühendisi & Fenerbahçe")
	private String     biography;

}

public class UserRequest {

@ApiModelProperty(example = "cem")

private String firstName;

@ApiModelProperty(example = "dirman")

private String lastName;

@ApiModelProperty(example = "[email protected]")

private String email;

@ApiModelProperty(example = "password")

private String password;

@ApiModelProperty(notes = "0 gönderilmeyecektir",example = "5394176264")

private String phone;

private GenderType gender;

@ApiModelProperty(notes = "url girilmelidir", example = "https://bilisim.io")

private String profileImage;

@ApiModelProperty(example = "bilgisayar mühendisi & Fenerbahçe")

private String biography;

}

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.



        @PostMapping(produces = MediaType.APPLICATION_JSON_VALUE)
        @ApiOperation(value = "Gönderilen kullanıcıyı kaydeder",response = UserResponse.class)
	@ApiResponses(value = {
			@ApiResponse(code = 201, message ="Kullanıcı oluşturuldu"),
			@ApiResponse(code = 401, message ="Yetkisiz işlem"),
			@ApiResponse(code = 400, message ="Bad request")
	})
	public ResponseEntity<ServiceReponse<UserResponse>> createUser(@Valid @RequestBody UserRequest userRequest)

@PostMapping(produces = MediaType.APPLICATION_JSON_VALUE)

@ApiOperation(value = "Gönderilen kullanıcıyı kaydeder",response = UserResponse.class)

@ApiResponses(value = {

@ApiResponse(code = 201, message ="Kullanıcı oluşturuldu"),

@ApiResponse(code = 401, message ="Yetkisiz işlem"),

@ApiResponse(code = 400, message ="Bad request")

})

public ResponseEntity<ServiceReponse<UserResponse>> createUser(@Valid @RequestBody UserRequest userRequest)

Kaynak;

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

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

Faydalı olması dileğiyle.