Awalnya mungkin dokumentasi hanya sekedar coretan-coretan para developer untuk mencatat bagaimana RESTful web service API mereka dapat dikonsumsi oleh client. Seiring berkembangnya lingkungan & percepatan development, serta pengujian, dibutuhkan dokumentasi yang terstruktur dan terstandar. Ketika service backend API kita sudah mulai semakin besar, atau mungkin memiliki endpoint yang banyak, atau bahkan terdiri dari banyak services. Bagaimana kita menyimpan dokumentasi tersebut agar mudah diatur, mudah digunakan, dan bahkan dapat diotomatisasi? Sudah seharusnya kita mendokumentasikannya dengan format yang disepakati.

Saat ini sudah ada banyak format dokumentasi, seperti io-docs, blueprint, raml, dan lainnya. Awalnya, kami pun menggunakan format blueprint, karena dulu apiary kami jadikan host dokumentasi API kami. Lalu kami mulai merasakan adanya kekurangan dan membutuhkan alternatif yang lebih baik. Lalu kami menjatuhkan pilihan pada yang satu ini, mari berkenalan dengan OpenAPI.

Sejarah OpenAPI

Pada 2010, Tony Tam yang bekerja di Wordnik memulai pengembangan swagger specification, sebuah standar format dokumentasi API. Lalu 2015 SmartBear mengakuisisi Swagger API specification tersebut dan mendonasikannya kepada organisasi baru yang disebut OpenAPI Initiative di bawah sponsor Linux Foundation. Di tahun 2016, Swagger specification diganti dengan nama OpenAPI Specification (OAS), lalu versi 3.0.0 dirilis pada tahun 2017.

Selain Linux Foundation, member lainnya adalah 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet. Sekarang anda paham kan kenapa OpenAPI lebih menarik?

Definisi

Ada 3 definisi yang membedakan jenis dokumentasi API ini 1.

  • API Documentation yang ditujukan untuk manusia yang mudah dibaca dan dimengerti.
  • API Specification lebih terstruktur dan programmable. Menjelaskan bagaimana API tertentu bekerja, karakteristik nya dan apa yang akan dihasilkannya.
  • API Definition, ditujukan untuk dikonsumsi mesin agar dapat diotomatisasi dan dapat dibuat mock server

Dari apa yang kami pelajari, API specification menjadi penengah antara documentation & definition, masih mudah dibaca manusia, tapi juga bisa ditranslate untuk menjadi mock server sebagai virtual API testing.

Tools

Swagger sendiri sebenarnya sudah menyediakan beberapa tools untuk menunjang dokumentasi API kita, yaitu:

1. swagger-editor

Anda dapat mengunjungi online editor nya di sini . Bagi yang baru dengan API spec, text di sebelah kiri adalah API spec, dan kita bisa save text tersebut menjadi yaml/json file.

Ya betul, pertama kali anda membukanya, anda akan melihat dokumentasi dengan specification swagger 2. Anda dapat mengubahnya dengan klik menu edit > convert to openAPI 3 > confirm.

2. swagger-ui

Jika kita hanya perlu html generator nya, kita bisa menggunakan swagger-ui. Dari text yang berformat di sebelah kiri tadi, swagger ui mentraslasinya menjadi html yang mudah dibaca melalui browser.

3. swagger-codegen

Code-generator untuk membuat server stubs dan client SDKs secara langsung dari API specification yang telah kita buat, dari swagger-editor yang tadi kita tinggal pilih menu "Generate Server" dan pilih bahasa yang diinginkan.

Dengan ketiga tools tersebut, kita dapat mengkombinasikannya untuk membuat dokumentasi API internal organisasi kita. Sekian perkenalan api dokumentasi dengan OpenAPI, saya cukupkan sesi tulisan kali ini. Terima kasih sudah berkunjung.

+staypositive

Ciao!