Easy and Fast API Delivery with Swagger

Pada common practice di lapangan, saat kita berperan sebagai backend developer, tentu sangat penting untuk berkomunikasi dengan frontend developer mengenai API apa saja yang kita sediakan dan dapat digunakan oleh tim frontend. Typically yang diperlukan adalah dokumentasi yang sering disebut sebagai techdoc atau technical documentation. Lalu bagaimana bentuk dokumentasi ini?

Cara paling mudah ya bisa saja dengan dokumen sederhana seperti Word atau Excel. However karena program-program semacam ini tidak spesifik diperuntukan untuk pembuatan dokumentasi, it could lead to some drawbacks.

• Sulit untuk membuat dokumentasi yang jelas, detil, terstruktur dan terorganisir dengan baik. If only dibuat standarisasi format mengenai bagaimana dokumen ini dibuat, dokumentasi semacam ini akan sulit untuk dikonsumsi.
• Additional softwares are needed. Dengan menggunakan tools seperti Word atau Excel, kita memerlukan software tersebut ter-install dan tanpa adanya program ini, dokumentasi tidak dapat digunakan.
• Dokumen semacam ini biasanya statis dan tidak seamless untuk proses update dan collaboration. Artinya, apabila changes terjadi pada API, dokumentasi ini akan dengan cepat menjadi outdated dan sulit di-maintain.

Saya ingin memperkenalkan pada fellowdevs sebuah tool yang dapat membantu kita dalam men-deliver API kita melalui sebuah UI yang interaktif dan dapat langsung di-test oleh tim frontend.

Tool yang saya maksud ini adalah Swagger. Swagger ini open source dan sudah cukup banyak integrasinya ke banyak platform salah satunya yang akan kita gunakan, Spring Boot. Konfigurasinya pun sangat mudah, bahkan I have to say it's too easy 😂

Lalu bagaimana bentuk Swagger ini kok bisa sampai memudahkan delivery API kita? Nah, nantinya, dokumentasi API kita yang dapat dikonsumsi oleh tim frontend berbentuk demikian.

Nice, isn't it? Bahkan, Swagger memungkinkan kita untuk melakukan hit ke endpoint API tersebut, sehingga penerima dokumentasi dapat langsung melakukan verifikasi dengan cepat (rapid testing) apakah API yang kita sediakan dapat mereka pergunakan atau tidak.

Selain itu, Swagger dirancang khusus untuk keperluan dokumentasi API dan sudah sesuai dengan standar Open API. Oleh karena itu hasil dokumentasi dari Swagger dapat dengan mudah dan jelas untuk digunakan oleh para developer, seperti frontend devs. Ditambah lagi, Swagger juga sudah menyediakan fitur-fitur seperti data validation, code generation dan integrasi ke banyak development tools. Swagger menjamin dokumentasi yang dihasilkan menjadi tetap akurat dan updated dengan effort yang minim.

Untuk mencoba menggunakan Swagger, kita akan menggunakan project backend API yang saya tulis untuk materi program BCA Advisory Program yaitu Advisory Program 2022 (Chapter 1) : Create Your First API.

Tambahkan dependency Swagger pada pom.xml.

1<!-- SWAGGER -->
2<dependency>
3	<groupId>io.springfox</groupId>
4	<artifactId>springfox-boot-starter</artifactId>
5	<version>3.0.0</version>
6</dependency>
7<dependency>
8	<groupId>io.springfox</groupId>
9	<artifactId>springfox-swagger-ui</artifactId>
10	<version>3.0.0</version>
11</dependency>

Selanjutnya buat file baru untuk melakukan konfigurasi Swagger. Pada case saya, saya buat class SwaggerConfig.java di dalam folder /com/bca/adam/config/. Tambahkan konfigurasi Swagger berikut.

1package com.bca.adam.config;
2
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5
6import springfox.documentation.builders.PathSelectors;
7import springfox.documentation.builders.RequestHandlerSelectors;
8import springfox.documentation.spi.DocumentationType;
9import springfox.documentation.spring.web.plugins.Docket;
10
11@Configuration
12public class SwaggerConfig {
13    @Bean
14    public Docket api() {
15        return new Docket(DocumentationType.SWAGGER_2)
16                .select()
17                .apis(RequestHandlerSelectors.basePackage("com.bca.adam"))
18                .paths(PathSelectors.any())
19                .build();
20    }
21}

Ini adalah konfigurasi minimal yang perlu kita lakukan untuk Swagger. Perlu diperhatikan bahwa kita mendefinisikan basePackage untuk Swagger melakukan scanning terhadap komponen-komponen di dalam project kita. Ubah value properti ini sesuai dengan struktur project kalian.

Berikutnya, kita perlu mengaktifkan Swagger dan WebMvc. Aktifasi Swagger dapat kita lakukan melalui anotasi @EnableSwagger2. Sedangkan WebMvc diaktifkan dengan anotasi @EnableWebMvc. Sebagai informasi, Swagger UI sudah menyediakan UI-nya sendiri, dimana di dalamnya tentu terdapat komponen-komponen view. Spring, memerlukan konfigurasi view resolver apabila digunakan untuk membuat aplikasi web yang dapat menghasilkan UI. Salah satu syaratnya, dengan mengaktifkan modul MVC di dalamnya. Inilah alasan mengapa kita memerlukan aktifasi WebMvc.

Masih berhubungan dengan view resolver, kita perlu memberi tahu Spring, bahwa kita menggunakan resolver dari internal. Resolver ini digunakan agar Spring dapat me-render halaman UI Swagger tadi. Tambahkan konfigurasi @Bean berikut.

1package com.bca.adam;
2
3import org.springframework.boot.SpringApplication;
4import org.springframework.boot.autoconfigure.SpringBootApplication;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.ComponentScan;
7import org.springframework.web.servlet.config.annotation.EnableWebMvc;
8import org.springframework.web.servlet.view.InternalResourceViewResolver;
9
10import springfox.documentation.swagger2.annotations.EnableSwagger2;
11
12@SpringBootApplication
13@ComponentScan(basePackages = "com.bca.adam")
14@EnableWebMvc
15@EnableSwagger2
16public class AdamApplication {
17
18	public static void main(String[] args) {
19		SpringApplication.run(AdamApplication.class, args);
20	}
21
22	@Bean
23	public InternalResourceViewResolver defaultViewResolver() {
24		return new InternalResourceViewResolver();
25	}
26}
27

As easy as it looks, dengan menggunakan Swagger, kita baru saja membuat dokumentasi API yang jelas, interaktif, mudah digunakan, dan terorganisir hanya dalam 3 langkah! Amazing bukan? Bayangkan apabila kita perlu membuat dokumen ini menggunakan Word atau Excel 😵‍💫

Untuk mengakses dokumentasi kita, cukup buka browser dan arahkan ke URL aplikasi kita dengan tambahan path /swagger-ui/. And voila!

Explore-lah untuk mengetahui apa saja yang sudah di-generate untuk kita. Swagger memiliki konfigurasi yang sangat configurable dan mudah, konfigurasi kita tadi adalah bare minimum saja. Fellowdevs dapat lakukan konfigurasi sendiri sesuai official docs mereka ya.

Sekarang, kita tinggal deploy aplikasi kita ke shared server atau deployment environment lainnya seperti cloud dan kemudian cukup berikan URL ke frontend developer 🎉