Pendahuluan mengenai Dokumentasi API, silahkan lihat di sini

Mengenai OpenAPI sendiri, silahkan lihat di sini

Swagger vs OpenAPI , lihat di sini

Springfox menggunakan Swagger versi 2 , lihat di sini

Di artikel artikel awal diatas, kita melihat bagaimana kita membuat konfigurasi agar kita dapat menggunakan SpringFox untuk menampilkan dokumentasi API di Spring Boot dengan spesifikasi swagger v2.


Sekarang coba kita lihat untuk case menggunakan spesifikasi OpenAPI v3.

Dengan berubahnya spesifikasi dokumentasi dari Swagger 2.0 ke Open API 3.0, maka banyak perubahan yang terjadi.

Termasuk di dalamnya juga untuk library pendukung Spring Boot untuk membuat Dokumentasi API dari SpringFox.

Mereka juga melakukan adaptasi terhadap perubahan dari swagger menjadi Open API.

Akan tetapi ada library baru lain yang sudah segera mengadopsi OpenAPI v3 ini secara cepat, dan tanpa peduli dengan spesifikasi Swagger 2.0 yang sebelumnya.

Yaitu Springdoc-openapi.


Apa kelebihannya ?

Kelebihan SpringDoc ini adalah :

  • Langsung support OpenAPI v3 dan tidak mendukung spesifikasi Swagger 2.0, sehingga tidak memikirkan kompatibilitas dengan spesifikasi Swagger v2.
  • merupakan library yang standalone dan tidak mengimport library Spring Boot lainnya secara berlebihan. Tidak seperti springfox yang banyak memakai wrapper untuk mengimport banyak library Springboot didalamnya.
  • library nya juga satu .jar saja, karena didalamnya sudah terintegrasi dengan tampilan antarmuka UI web nya. Tidak seperti springfox yang harus import librarynya dan juga library antarmuka web nya.

Bagaimana cara importnya ?

Seperti biasa, kalau kita memakai pom.xml, maka kita cukup mengimport dependency sbb :

<dependency>
	 <groupId>org.springdoc</groupId>
	 <artifactId>springdoc-openapi-ui</artifactId>
	 <version>1.6.9</version>
</dependency>

Sudah begitu saja, library ini akan include code dan juga antarmukanya dengan tools Swagger.

Dan yang akan dilakukan oleh library tersebut adalah :

  • secara otomatis akan deploy swagger-ui ke aplikasi spring boot nya.
  • dokumentasinya akan dapat dilihat dalam bentuk HTML, dengan memakai bantuan library swagger-ui
  • halaman swagger nya akan berlokasi di : http://server:port/context-path/swagger-ui.html
  • deskripsi API dalam bentuk json akan tersedia di : http://server:port/context-path/v3/api-docs

Bagaimana kalau kita butuh konfigurasi detail untuk API nya.

Tentu saja bisa.

Di Springdoc, padanan dari Doclet dari swagger v2 adalah OpenApi object.

Misalnya :

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI exampleOpenAPI() {
	ApiInfo apiInfo = new ApiInfoBuilder().title("API for xxx")
				.description("Description API for xxx")
				.termsOfServiceUrl("TC for xxx")
				.contact(new Contact("Contact", "URL", "Email"))
				.license("Apache 2.0")
				.licenseUrl("URL license")
				.version("1.0").build();

        return new OpenAPI().info(apiInfo);
    }
}

atau kalau misalnya kita mempunyai konfigurasi yang berbeda untuk kasus-kasus tertentu.

Misalnya pakai Header Authorization kalau lewat gateway.

Akan tetapi pakai Header username password kalau langsung ke servicenya.

Maka kita bisa membuat 2 Group OpenAPI di tampilannya nanti agar bisa ditest dan dicek spesifikasinya sesuai dengan group kasusnya.

Misalnya :

public GroupedOpenApi directGroupedOpenAPI() {

	// buat customizer untuk operation open API
	OperationCustomizer operationCustomizer = (Operation operation, HandlerMethod handlerMethod) -> {
			operation.addParametersItem(xxxxx);
			return operation;
	};

  	// buat OpenApi spec untuk kasus tertentu
	return GroupedOpenApi.builder()
	      	.group(group.getName())
	  	.packagesToScan(group.getBasePackage())
		.pathsToMatch(group.getPathSelector())
		.addOperationCustomizer(operationCustomizer)
		.build();
}