OpenAPI

Eko Kurniawan Khannedy

Eko Kurniawan Khannedy

- Technical architect at one of the biggest

ecommerce company in Indonesia
- 10+ years experiences
- www.programmerzamannow.com
- youtube.com/c/ProgrammerZamanNow
Eko Kurniawan Khannedy

● Telegram : @khannedy
● Facebook : fb.com/ProgrammerZamanNow
● Instagram : instagram.com/programmerzamannow
● Youtube : youtube.com/c/ProgrammerZamanNow
● Telegram Channel : t.me/ProgrammerZamanNow
● Email : [email protected]
Sebelum Belajar

● HTTP
● RESTful API
Agenda
● Pengenalan OpenAPI
● Tipe Data
● Document
● Info
● Component
● Path
● Tag
● Security
● Dan lain-lain
Pengenalan OpenAPI
Pengenalan OpenAPI

● OpenAPI merupakan standar spesifikasi, tidak tergantung bahasa pemrograman apapun, untuk
membuat dokumentasi RESTful API.
● OpenAPI dibuat agar pengguna RESTful API tidak perlu mengakses kode aplikasi dan membaca
dokumen manual (misal dalam bentuk doc, pdf) untuk memahami RESTful API yang dibuat
● OpenAPI bisa menggunakan tool untuk menampilkan secara visual, bahkan untuk membuat kode
program client atau server
● https://www.openapis.org/
● https://github.com/OAI/OpenAPI-Specification
● https://swagger.io/specification/
Document Structure

● OpenAPI memiliki struktur document yang sudah standar

● Namun kita diberi dua opsi untuk membuat document nya, bisa menggunakan JSON atau YAML
● https://www.json.org/
● https://yaml.org/
OpenAPI Editor

● Document OpenAPI hanya menggunakan JSON atau Yaml, jadi untuk membuat document
OpenAPI kita cukup menggunakan Text Editor
● Namun jika kita ingin melihat OpenAPI dalam bentuk visual, kita juga bisa menggunakan Swagger
Editor : https://editor.swagger.io/
● Jika menggunakan product JetBrains, bisa menggunakan plugin OpenAPI
https://www.jetbrains.com/help/idea/openapi.html
● Jika menggunakan Visual Studio Code, bisa menggunakan plugin OpenAPI
https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi
Tipe Data
Tipe Data

● Saat kita membuat RESTful API, sudah dipastikan kita akan membuat request dan response,
dimana dalam data request dan response sudah dipastikan terdapat detail data
● Misal jika terdapat data Product, pasti ada id, name, price, dan lain-lain
● Semua detail data tersebut pasti memiliki tipe data
● Kita tidak bisa menggunakan tipe data yang terdapat pada bahasa pemrograman yang digunakan
untuk membuat RESTful API, oleh karena itu pada OpenAPI terdapat tipe data general yang bisa
digunakan yang dapat dimengerti di semua bahasa pemrograman
OpenAPI Tipe Data (1)
OpenAPI Tipe Data (2)
Document
Document
● OpenAPI sangatlah sederhana, kita hanya perlu membuat satu file berisi semua data OpenAPI
nya
● OpenAPI memiliki struktur yang sudah ditentukan ketika membuat document nya
● Kita bisa menggunakan JSON atau YAML untuk file nya
● https://spec.openapis.org/oas/v3.0.3#openapi-object
OpenAPI Object (1)
OpenAPI Object (2)
Kode : OpenAPI Document
Info
Info
● Info merupakan bagian dari informasi metadata tentang API yang kita buat
● Kita bisa memasukkan author, lisensi, dan lain-lain
Info Object
Contact Object
License Object
Kode : Info
Server
Server
● Saat kita membuat API sudah pasti terdapat server RESTful API yang nanti akan kita buat
● Kita bisa memberitahu server yang tersedia di OpenAPI
● Misal, terdapat server development, staging, production dan lain-lain
Server Object
Kode : Server
External Documentation
External Documentation

● External documentation merupakan bagian dalam OpenAPI jika kita ingin menambahkan link
tambahan dalam OpenAPI
● Bisa menuju link documentation lain, atau mungkin link menuju website
External Documentation Object
Kode : External Documentation
Path
Path
● Path merupakan representasi endpoint API di OpenAPI
● Pada Path, kita tidak perlu menuliskan seluruh URL, cukup url di belakang setelah lokasi server
Path Object
Path Item Object (1)
Path Item Object (2)
Path Operation
Kode : Path
Operation
Operation
● Setiap Path yang kita buat di OpenAPI, bisa memiliki lebih dari satu Operation
● Hal ini dikarenakan, dalam HTTP, satu URL bisa memiliki beberapa HTTP Method
● Misal url untuk mengambil semua data dan membuat data baru, mungkin url nya sama, yang
membedakan adalah HTTP Method nya, GET untuk mengambil data, POST untuk membuat data
● Inti dari API Documentation adalah dokumentasi operation yang terdapat pada RESTful API yang
kita buat
Operation Object (1)
Operation Object (2)
Operation Object (3)
Kode : Operation
Parameter
Parameter
● Parameter adalah data yang dikirim tidak melalui Request Body
● Operation bisa memiliki parameter lebih dari satu
● OpenAPI mendukung beberapa jenis parameter, yaitu Query Parameter, Path Variable, Header,
dan Cookie
● Kita bisa menambahkan parameter pada Operation, sehingga pengguna bisa tahu bahwa ada
parameter yang perlu dikirim ketika memanggil Operation tersebut
Parameter Object (1)
Parameter Object (2)
Kode : Parameter (1)
Kode : Parameter (2)
Schema
Schema
● Saat kita membuat parameter, kita mungkin ingin memberitahu tentang tipe data untuk
parameter tersebut
● Parameter memiliki attribute bernama schema, dimana schema sebenarnya sangat kompleks, kita
akan bahas secara bertahap
● Dimulai dari simple schema, misal tipe data yang sebelumnya sudah kita bahas
JSON Schema Specification

● Schema menggunakan JSON Schema untuk mendefinisikan struktur datanya

● JSON Schema bisa berisikan tipe sederhana, seperti number, string, boolean dan lain-lain, atau
bahkan tipe data kompleks, seperti object dan array (yang akan kita bahas nanti)
● https://json-schema.org/
● https://json-schema.org/draft/2020-12/json-schema-core.html
Kode : Schema
JSON Schema Validation

● Schema mendukung JSON Schema Validation

● Hal ini membuat kita bisa memberitahu validasi yang diperlukan ketika pengguna membaca
OpenAPI kita
● Dengan kita tambahkan Schema Validation, pengguna RESTful API kita bisa tahu validation yang
kita buat tanpa harus kita buat dokumentasi secara terpisah
● https://json-schema.org/draft/2020-12/json-schema-validation.html
Kode : Schema Validation
Request Body
Request Body

● OpenAPI juga mendukung dokumentasi untuk request body

● Dengan ini, kita memberi tahu tentang schema request body yang harus dikirim ketika
menggunakan RESTful API kita
● Request body mendukung schema, sehingga kita memberi tahu bentuk schema format data,
bahkan validasi yang diperlukan
Request Body Object
Media Type Object
Kode : Request Body
Object Schema
Object Schema

● Sebelumnya kita hanya membuat schema sederhana, seperti schema tipe data boolean atau string
● Spesifikasi di JSON Schema juga mendukung pembuatan schema berupa objek, yaitu data yang
memiliki attribute lebih dari satu
Kode : Object Schema
Array Schema
Array Schema

● Selain tipe data object, Schema juga mendukung tipe data array
● Saat membuat tipe data array, kita juga bisa menentukan tipe data items yang terdapat di array,
bisa tipe data sederhana, bisa tipe data kompleks seperti object atau array lagi
Kode : Array Schema
Example
Example
● OpenAPI mendukung example data
● Example data merupakan data contoh yang bisa kita tambahkan baik itu di Parameter, Request
Body dan Response Body
Kode : Example di Parameter
Kode : Example di Request Body
Response Body
Response Body

● Selain Request Body, kita juga mendokumentasikan Response Body di OpenAPI

● Dengan demikian, kita bisa memberi tahu format Response Body yang kita kembalikan pada
RESTful API yang kita buat
● Yang menarik di OpenAPI, kita bisa memberi tahu format response body sesuai dengan response
status nya, misal kita bisa tentukan untuk response status 200, 400, 500, dan lain-lain
Response Body Object
Response Object
Kode : Response Body
Tag
Tag
● Tag merupakan fitur tambahan, dimana kita bisa grouping beberapa Path menjadi satu Tag yang
sama
● Misal ketika kita membuat OpenAPI untuk RESTful API Toko Online, kita grouping dengan Tag
Product, Customer, Payment, Order, dan lain-lain
Kode : Tag
Component
Component
● Component merupakan bagian dalam OpenAPI untuk menyimpan object yang bisa digunakan
ulang
● Misal, saat nanti kita membuat spek untuk Request Body atau Response Body, dibanding kita
buat satu persatu, jika ada beberapa yang sama, lebih baik kita buat dalam Component, sehingga
bisa digunakan di beberapa Endpoint API
● Ada banyak jenis component, ada schema, request, response, parameter, header, dan lain-lain
Component Object (1)
Component Object (2)
Kode : Component
Reference
Reference

● OpenAPI memiliki fitur reference, dimana dengan reference kita bisa membuat reference ke data
component yang sudah kita buat
● Hal ini lebih baik, daripada kita buat component yang sama berkali kali pada beberapa path, misal
jika terdapat response body yang sama, lebih baik kita gunakan reference, jika memiliki parameter
yang sama, lebih baik kita gunakan reference
Kode : Reference pada Parameter
Kode : Reference pada Response Body
Security
Security
● OpenAPI mendukung dokumentasi untuk Security RESTful API
● Dengan ini kita bisa memberitahu pengguna mekanisme Security apa yang kita gunakan di
RESTful API kita
● Ada banyak format security yang didukung oleh OpenAPI, seperti apiKey (query param, header,
cookie), http (basic auth, bearer token), oauth2 dan openIdConnect
● Sebelum menggunakan fitur Security, kita perlu membuat requirement Security terlebih dahulu di
Component, baru kita bisa gunakan di Operation
Security Object (1)
Security Object (1)
Kode : Security
Kode : Security di Operation
Code Generator
Code Generator

● OpenAPI adalah spesifikasi yang standard, dan banyak diadopsi oleh banyak perusahaan
● Bahkan kita bisa melakukan code generator sesuai dengan bahasa pemrograman yang kita
inginkan
● Contohnya kita bisa menggunakan https://editor.swagger.io/ untuk membuat code client atau
server sesuai dengan OpenAPI file yang kita buat
● Hal ini bisa mempermudah ketika kita butuh membuat kode client atau server yang sesuai dengan
OpenAPI spec yang sudah dibuat
Swagger Code Generator
Penutup
Penutup
● Masih banyak fitur yang terdapat di OpenAPI, silahkan pelajari langsung di halaman websitenya
● Mulai sekarang selalu gunakan OpenAPI untuk membuat dokumentasi RESTful API
● Buatlah OpenAPI sebelum kita membuat aplikasi RESTful API
● OpenAPI bisa digunakan sebagai kontrak kesepakatan antara yang akan membuat RESTful API
dan yang akan menggunakan RESTful API