Pendahuluan mengenai Dokumentasi API, silahkan lihat di sini

Mengenai OpenAPI sendiri, silahkan lihat di sini

Swagger vs OpenAPI , lihat di sini


Ok, sekarang lanjut !

Seperti dijelaskan di sini dan di sini , maka sejak 2015 , maka spesifikasi untuk mendokumentasikan REST API mengerucut kepada Spesifikasi OpenAPI saja, yang sebelumnya dinamakan Spesifikasi Swagger.

Sehingga sekarang kalau berbicara tentang spesifikasi dokumentasi REST API terbaru, maka kita bisa dipastikan akan bicara tentang Spesifikasi OpenAPI 3.0.0.

Kalau berbicara mengenai spesifikasi sebelumnya, maka kita akan bicara mengenai Spesifikasi Swagger 2.0.0.

Tidak ada lagi spesikasi Swagger selanjutnya, karena swagger yang disponsori oleh SmartBear sekarang fokus kepada pengembangan produk-produk implementasinya, dengan nama dagang yang sama yaitu Swagger, bukan lagi ke spesifikasinya.

Walaupun SmartBear tetap saja menjadi bagian dari Group Open Source OpenAPI yang bersama-sama mengembangkan spesifikasinya.

Perubahan dari Spesifikasi Swagger 2.0.0 ke Spesifikasi OpenAPI 3.0.0 cukup mendasar, terutama di sisi penamaan dan penyederhanaan spesifikasinya.

Jadi kalau menyebut Swagger, itu adalah nama produk implementasi OpenAPI dari perusahaan SmartBear.


Bagaimana dengan Spring-Boot

Ok..ok.

Bagi Java Software Engineer yang berkutat dengan REST API berbasiskan Spring Boot, maka istilah Swagger juga menjadi istilah umum.

Kerancuan antara spesifikasi yang dahulu bernama Swagger, dengan produknya SmartBear yang juga bernama Swagger memang menjadi permasalahan sendiri.

Tetapi sebenarnya sih ok saja, selama kita tahu posisi dan sejarahnya.

Spring boot sebagai sebuah framework juga mempunyai kebutuhan yang sama untuk mengimplementasikan OpenAPI secara otomatis untuk REST API yang dibuat dengan framework Spring-Boot.

Karena biasanya sudah ada library implementasi yang dibuat khusus untuk spring-boot, baik secara struktur JSON API nya maupun secara tampilan UI/web nya untuk ditest.

Bagi yang berkutat dengan spring boot , maka ada library yang kita gunakan biasanya (dulu) ketika masih spesifikasi swagger :

Namanya library SpringFox : http://springfox.github.io/springfox/docs/current/

SpringFox ini merupakan kumpulan library Java yang berguna untuk otomasi JSON Api dengan mengandalkan framework Spring. Membuat JSON API dari konfigurasi Spring, struktur calss, dan annotasi Java dan Spring

Springfox sendiri mengakomodasi spesifikasi dari banyak vendor, seperti Spesifikasi Swagger , RAML, dan juga JSONApi.


Apa yang perlu di tambahkan ketika menggunakan SpringFox ?

Ketika ingin menggunakan swagger dari library SpringFox, maka kita harus menambahkan library springfox-swagger2 (untuk Spesifikasi Swagger 2.0)..

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>3.0.0</version>
</dependency>

Untuk menandakan sebuah dokumentasi API, SpringFox sendiri menyebutnya Docket.

Docket artinya kesimpulan dari statement dari isi REST/Document.

Docket sebenarnya adalah konsep yang abstract, sebagai antarmuka utama dari dokumentasi API dari Springfox, dan merupakan Builder dari dokumentasi API.

Didalamnya terdapat konfigurasi parameter, bagian dokumentasi yang bisa ditambah dan dimodifikasi sesuai kebutuhan.


Contohnya seperti apa ?

Ok,

Untuk bisa menambahkan Swagger memakai SpringFox, maka kita harus menambahkan dependency springfox-swagger seperti diatas.

Kemudian kita perlu membuat konfigurasi sbb :

  • Tambahkan anotasi ini di atas class Konfigurasi :@EnableSwagger2 kalau memakai spesifikasi swagger 2.0
  • Tambahkan anotasi ini di atas class Konfigurasi :@EnableSwagger kalau memakai spesifikasi swagger 1.2
  • Buat file konfigurasi sbb :
@EnableSwagger2
@Configuration
public class SpringFoxConf() {

  @Bean
  public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .pathMapping("/")
        .directModelSubstitute(LocalDate.class, String.class)
        .genericModelSubstitutes(ResponseEntity.class)
  }

  ...
  ....
}

Didalam Docket diatas, kita bisa menambahkan konfigurasi spesifik, misalnya Authorization code, header parameter, dsb.

Kita lanjut ke part 2