Sebelumnya, Anda mungkin telah menggunakan Swagger 2.0 (juga dikenal sebagai OAS 2), tetapi sekarang, saatnya untuk meningkatkan ke OpenAPI Specification (OAS) 3. Dalam artikel ini, kami akan menguraikan poin-poin penting dari proses peningkatan dan hal-hal penting dalam mendokumentasikan API menggunakan OAS 3.
Beberapa poin ini mungkin masih berlaku untuk dokumen OAS 2 sebelumnya (sebelumnya dikenal sebagai Swagger), tetapi perlu dicatat karena saya mungkin belum sepenuhnya menekankannya sebelumnya.
Contoh kode dalam artikel ini diekstraksi dari spesifikasi OAS 3 dari bookmarks.dev-api, yang tersedia dalam file openapi.yaml di GitHub. Hasilnya dapat dilihat di bookmarks.dev/api/docs/.
Berikut adalah sepuluh pertimbangan utama:
1. Baca Dokumen Spesifikasi
Baca artikel "A Guide to What's New in OpenAPI 3.0," yang membagikan beberapa pembaruan utama dalam versi terbaru OAS dan memberikan wawasan terperinci tentang apa yang perlu Anda ketahui saat beralih dari OAS 2.0 ke OAS 3.0. Artikel ini didasarkan pada webinar 1 jam "OpenAPI 3.0, And What it Means for the Future of Swagger."
2.Gunakan Layanan Web Konverter
Gunakan layanan web konverter OpenAPI/Swagger 2.0 ke OpenAPI 3.0 untuk mengubah spesifikasi Swagger Anda menjadi OpenAPI 3.0.
Ini tersedia online di https://converter.swagger.io/, dan Anda juga dapat menggunakannya sebagai gambar Docker:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3.Validasi Spesifikasi Anda dan Pratinjau dengan Swagger Editor
Swagger Editor memungkinkan Anda untuk mengedit spesifikasi Swagger API berformat YAML di peramban web Anda dan langsung melihat pratinjau dokumentasi.
Anda dapat menggunakannya secara online atau sebagai versi yang diterbitkan npm atau gambar Docker. Untuk detail lebih lanjut, lihat README proyek.
4.Pamerkan Dokumentasi Anda dengan Swagger UI
Swagger UI adalah kumpulan sumber daya HTML, JavaScript, dan CSS yang secara dinamis menghasilkan dokumentasi yang indah untuk API yang sesuai dengan Swagger.
Anda dapat menggunakannya secara langsung, seperti saya, dengan mengakses dokumentasi Swagger UI melalui rute API, misalnya, bookmarks.dev/api/docs/. Berikut adalah cuplikan kode dari app.js:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Menyertakan file spesifikasi terbuka (openapi.yaml) dalam nodemon watch Anda (mis., nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) dapat membantu, memungkinkan Anda untuk memuat ulang UI tanpa memulai ulang server ExpressJS secara manual.
4.1. Gunakan swagger-jsdoc untuk Pendekatan Code-First
Poin penting lainnya adalah Anda dapat menggunakan swagger-jsdoc untuk mengintegrasikan Swagger melalui anotasi JSDoc dalam kode Anda. Proyek swagger-jsdoc mengasumsikan bahwa Anda ingin mendokumentasikan kode yang ada, aktif, dan berfungsi dengan cara yang "menghidupkan" kode tersebut, menghasilkan spesifikasi yang dapat dimasukkan ke dalam alat Swagger lainnya daripada sebaliknya.
Saat ini, saya mengelola dokumentasi dalam satu file openapi.yaml, tetapi saya mungkin mempertimbangkan untuk menggunakannya di masa mendatang.
5.Kelompokkan Operasi Menggunakan Tag
Anda dapat menetapkan daftar tag ke setiap operasi API, sehingga memudahkan Swagger UI dan Swagger Editor untuk menampilkan operasi berdasarkan tag. Untuk mengontrol pengurutan di Swagger UI, Anda perlu menambahkannya sebagai tag global di tingkat root. Anda juga dapat menambahkan deskripsi dan tautan ke dokumen eksternal di sana.
Berikut adalah tag yang saya gunakan untuk API:
yamlCopy code
tags:- name: rootdescription: Digunakan untuk menandai titik akhir root- name: versiondescription: Akses versi proyek dan gitSha1- name: public-bookmarksdescription: Akses bookmark publik- name: personal-bookmarksdescription: Operasi pada bookmark pribadi- name: user-datadescription: Operasi pada data pengguna- name: helperdescription: Titik akhir/operasi pembantu
6.Tentukan URL Dasar API dengan Server
Di OpenAPI 3.0, Anda menggunakan array servers untuk menentukan satu atau lebih URL dasar untuk API. Server menggantikan kata kunci host, basePath, dan schemes yang digunakan di OpenAPI 2.0. Setiap server memiliki URL dan deskripsi opsional dalam format Markdown.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: Server lokal untuk pengembangan- url: https://www.bookmarks.dev/apidescription: Server utama (produksi)
7.Tentukan dan Gunakan Kembali Sumber Daya dengan Komponen
Seringkali, beberapa operasi API berbagi parameter umum atau mengembalikan struktur respons yang sama. Untuk menghindari duplikasi kode, Anda dapat menempatkan definisi umum di bagian components global dan mereferensikannya menggunakan $ref.
Misalnya, untuk respons yang umum untuk beberapa operasi di mana daftar bookmark muncul, saya mendefinisikan BookmarkListResponse di bawah components > responses:
components:responses:BookmarkListResponse:description: Daftar bookmarkcontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
Dan kemudian, saya mereferensikannya dalam operasi yang berbeda, seperti get-public-bookmarks:
yamlCopy code
/public/bookmarks:get:summary: Kembalikan daftar bookmark publik menggunakan parameter kueri.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"
Perhatikan locationQueryParam yang disebutkan di atas. Ini didefinisikan di bawah components > parameters dan direferensikan di beberapa tempat dalam spesifikasi API, termasuk contoh yang ditunjukkan di atas.
8.Tambahkan Contoh untuk Kejelasan
Anda dapat menambahkan contoh ke parameter, properti, dan objek untuk membuat spesifikasi layanan Web Anda lebih jelas. Contoh dapat dibaca oleh alat dan pustaka untuk API Anda. Misalnya, alat API tiruan dapat menggunakan nilai contoh untuk menghasilkan permintaan tiruan. Anda dapat menentukan contoh untuk objek, properti individual, dan parameter operasi menggunakan kunci example atau examples.
Misalnya, Anda dapat memiliki nilai kompleks sebagai contoh untuk parameter teks pencarian:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
Kueri pencarian (kata-kata dipisahkan oleh spasi). Filter khusus tersedia:
* `lang:iso_language_code` - mis., `lang:en` untuk bahasa Inggris, `lang:es` untuk bahasa Spanyol, `lang:de` untuk bookmark bahasa Jerman
* `site:site_URL` - mis., kembalikan bookmark dari [www.codepedia.org](htt