Pada tahap ini kita akan mencoba membuat semua API Spesification yang berhubungan dengan API yang akan kita buat sehingga kita perlu dokumentasi yang lengkap dengan menggunakan OpenAPI. Jika teman-teman belum memasang OpenAPI di repositorynya maka coba baca terlebih dahulu artikel sebelumnya.
Get Article List
Jadi pertama kita akan membuat list API Article ini dengan menambahkan satu API pada dokumentasi OpenAPI yang sebelumnya sudah kita definisikan.
{
"openapi": "3.0.2",
"info": {
"title": "Article RESTFul API",
"version": "1.0"
},
"servers": [
{
"url": "http://localhost:8080"
}
],
"paths": {
"/articles": {
"get": {
"description": "List All Articles",
"summary": "List All Articles",
"tags": [
"Article API"
],
"responses": {
"200": {
"description": "Success get all articles",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at":{
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
Create Article
Selanjutnya kita akan menambahkan endpoint Create data article yang mana nantinya API ini digunakan untuk menambahkan data ke dalam database.
{
...
...
"paths": {
"/articles": {
...
"post": {
"description": "Create new article",
"summary": "Create New Article",
"tags": [
"Article API"
],
"requestBody":{
"content": {
"application/json":{
"schema":{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at":{
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success create new article",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at":{
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
Karena response yang sama kita pakai itu dari ke dua endpoint ini, maka kita akan buat berupa komponen agar bisa dipakai di setiap endpoint karena hal tersebut memiliki kesamaan data. Bisa dilihat dibawah ini perubahannya.
{
"paths": {
...
...
},
"components": {
"schemas": {
"Article": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at":{
"type": "string"
}
}
}
}
}
}
}
}
}
Simpan komponen tersebut di bawah tag paths lalu hapus beberapa skema yang sudah dipakai di setiap endpoint tadi dan ubah menjadi ini.
{
"items": {
"$ref": "#/components/schemas/Article"
}
}
Get Single Data Article
Dilanjutkan dengan membuat dokumentasi API Spesification untuk get single data article seperti dibawah ini. Karena get data article ini menggunakan method GET maka kita masukkan pada JSON tags yg GET.
"/articles/{article_id}":{
"get":{
"description": "Get Single Article",
"summary": "Get Single Article by ID",
"tags": [
"Article API"
],
"parameters": [
{
"name": "article_id",
"in":"path",
"description": "Article Id"
}
],
"responses": {
"200": {
"description": "Success get article 1",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
}
}
}
}
}
}
}
Update Data Article
membuat dokumentasi API Spesification untuk update data article seperti dibawah ini. Karena parameter-nya itu sama dengan Get Article maka bisa dipakai seperti dibawah ini.
"/articles/{article_id}":{
"put":{
"description": "Update Article",
"summary": "Update Article by ID",
"tags": [
"Article API"
],
"parameters": [
{
"name": "article_id",
"in":"path",
"description": "Article Id"
}
],
"requestBody":{
"content": {
"application/json":{
"schema":{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at":{
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success update article 1",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
}
}
}
}
}
}
}
Request body untuk Create dan Update ini memiliki JSON yang sama maka kita akan buat component baru seperti ini
{
...
"CreatOrUpdateArticle": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
...
}
Lalu kita update RequestBody dari API Spesification Create dan Update menjadi ini.
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatOrUpdateArticle"
}
}
}
},
}
Delete Data Article
Untuk membuat API Spesification untuk hapus data Article itu sama seperti halnya Get data article sehingga kita bisa copy saja dan ubah beberapa komponen dan method-nya menjadi DELETE.
{
"delete": {
"description": "Delete Article",
"summary": "Delete Article by ID",
"tags": [
"Article API"
],
"parameters": [
{
"name": "article_id",
"in": "path",
"description": "Article Id"
}
],
"responses": {
"200": {
"description": "Success delete article 1",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
}
}
}
}
}
}
}
}
}
API Spesification Security
Kita akan menambahkan juga security dari API Spesification yang akan kita buat. Saat ini kita akan buat yang sederhana saja dengan membuat component tambahan seperti ini.
{
"securitySchemes": {
"articleAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Authentication for Article API"
}
}
}
Maka pada tampilan swager UI-nya akan terlihat tombol Auhorize dan jika di klik akan menampilkan seperti ini.
Lalu tambahkan di setiap endpoint API Specification yang sudah kita buat dengan menambahkan component yang telah dibuat diatas menjadi seperti ini.
{
"security": [
{
"ArticleAuth": []
}
]
}
Lebih lengkapnya API Spesification JSON yang telah kita buat seperti ini
{
"openapi": "3.0.2",
"info": {
"title": "Article RESTFul API",
"version": "1.0"
},
"servers": [
{
"url": "http://localhost:8080"
}
],
"paths": {
"/articles": {
"get": {
"description": "List All Articles",
"summary": "List All Articles",
"tags": [
"Article API"
],
"security": [
{
"ArticleAuth":[]
}
],
"responses": {
"200": {
"description": "Success get all articles",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
}
}
}
}
}
},
"post": {
"description": "Create new article",
"summary": "Create New Articles",
"tags": [
"Article API"
],
"security": [
{
"ArticleAuth":[]
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatOrUpdateArticle"
}
}
}
},
"responses": {
"200": {
"description": "Success create new article",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
}
}
}
}
}
}
},
"/articles/{article_id}": {
"get": {
"description": "Get Single Article",
"summary": "Get Single Article by ID",
"tags": [
"Article API"
],
"security": [
{
"ArticleAuth":[]
}
],
"parameters": [
{
"name": "article_id",
"in": "path",
"description": "Article Id"
}
],
"responses": {
"200": {
"description": "Success get article 1",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
}
}
}
}
}
},
"post": {
"description": "Update Article",
"summary": "Update Article by ID",
"tags": [
"Article API"
],
"security": [
{
"ArticleAuth":[]
}
],
"parameters": [
{
"name": "article_id",
"in": "path",
"description": "Article Id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatOrUpdateArticle"
}
}
}
},
"responses": {
"200": {
"description": "Success update article 1",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Article"
}
}
}
}
}
}
}
}
},
"delete": {
"description": "Delete Article",
"summary": "Delete Article by ID",
"tags": [
"Article API"
],
"security": [
{
"ArticleAuth":[]
}
],
"parameters": [
{
"name": "article_id",
"in": "path",
"description": "Article Id"
}
],
"responses": {
"200": {
"description": "Success delete article 1",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"status": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ArticleAuth":{
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "Authentication for Article API"
}
},
"schemas": {
"CreatOrUpdateArticle": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"Article": {
"type": "object",
"properties": {
"id":{
"type": "number"
},
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at":{
"type": "string"
}
}
}
}
}
}
01 Pengenalan RESTful Pada Golang
Artikel Terhangat
Membangun API dengan Golang dan GraphQL
09 Sep 2024
Tutorial Microservices dengan Golang
07 Jul 2024
Membangun API dengan Golang dan GraphQL
