Difference between revisions of "Dokumentasi API dengan Swagger"

From OnnoWiki
Jump to navigation Jump to search
Line 1: Line 1:
−
# Modul 4.2: Dokumentasi API dengan Swagger
+
Oke Dzaq! Di bawah ini adalah panduan lengkap untuk membuat **modul dokumentasi API dengan Swagger** di **Ubuntu 24.04**. Kita akan pakai **FastAPI + Swagger UI** karena simpel dan cocok buat dokumentasi REST API secara otomatis.
  
−
## Pendahuluan
+
---
  
−
Dokumentasi yang baik sangat penting dalam pengembangan API untuk memastikan bahwa pengguna dan pengembang lain dapat memahami dan menggunakan API dengan efektif. Swagger adalah alat populer yang memungkinkan pengembang untuk mendokumentasikan, membangun, dan menguji API secara interaktif. Dalam modul ini, kita akan membahas cara menggunakan **Flasgger**, sebuah ekstensi Flask, untuk mendokumentasikan API yang telah dibuat.
+
## 🧩 1. **Install Python dan pip**
 +
Ubuntu 24.04 biasanya udah include Python 3. Tapi kita pastikan dulu:
  
−
## 1. Instalasi dan Konfigurasi Flasgger
+
```bash
−
 
+
sudo apt update
−
### a. Instalasi Flasgger
+
sudo apt install python3 python3-pip -y
 +
```
  
−
Pastikan Anda telah menginstal Flask. Jika belum, Anda dapat menginstalnya dengan perintah berikut:
+
---
  
 +
## 📦 2. **Buat Virtual Environment (opsional tapi disarankan)**
  
 
```bash
 
```bash
−
pip install Flask
+
sudo apt install python3-venv -y
 +
python3 -m venv venv
 +
source venv/bin/activate
 
```
 
```
−
 
  
−
Selanjutnya, instal Flasgger menggunakan pip:
+
---
  
 +
## 🔧 3. **Install FastAPI dan Uvicorn**
  
 
```bash
 
```bash
−
pip install flasgger
+
pip install fastapi uvicorn
 
```
 
```
−
 
  
−
### b. Konfigurasi Dasar Flasgger
+
---
−
 
 
−
Setelah instalasi, Anda dapat mengintegrasikan Flasgger ke dalam aplikasi Flask Anda. Berikut adalah contoh dasar konfigurasi Flasgger:
 
  
 +
## 📁 4. **Buat File Project: `main.py`**
  
 
```python
 
```python
−
from flask import Flask
+
# main.py
−
from flasgger import Swagger
 
  
−
app = Flask(__name__)
+
from fastapi import FastAPI
−
swagger = Swagger(app)
+
from pydantic import BaseModel
  
−
@app.route('/hello', methods=['GET'])
+
app = FastAPI(title="Swagger API - Metro TV", version="1.0")
−
def hello():
 
−
    """
 
−
    Endpoint untuk menyapa pengguna.
 
−
    ---
 
−
    responses:
 
−
      200:
 
−
        description: Berhasil menyapa pengguna.
 
−
    """
 
−
    return "Hello, World!"
 
  
−
if __name__ == '__main__':
+
# Contoh Model
−
     app.run(debug=True)
+
class Item(BaseModel):
−
```
+
     name: str
−
+
    price: float
 +
    is_offer: bool = None
  
−
Dalam contoh di atas, Flasgger secara otomatis menghasilkan dokumentasi untuk endpoint `/hello` berdasarkan docstring yang disediakan.
+
# Route dasar
 +
@app.get("/")
 +
def read_root():
 +
    return {"message": "Hello, Metro TV"}
  
−
## 2. Menambahkan Dokumentasi Interaktif untuk Endpoint
+
# Route dengan parameter
 +
@app.get("/items/{item_id}")
 +
def read_item(item_id: int, q: str = None):
 +
    return {"item_id": item_id, "q": q}
  
−
### a. Menggunakan Docstring untuk Dokumentasi
+
# POST endpoint
 +
@app.post("/items/")
 +
def create_item(item: Item):
 +
    return {"item": item}
 +
```
  
−
Flasgger memungkinkan Anda untuk mendokumentasikan endpoint langsung dalam docstring fungsi. Berikut adalah contoh bagaimana menambahkan dokumentasi untuk endpoint dengan parameter:
+
---
  
 +
## 🚀 5. **Jalankan API**
  
−
```python
+
```bash
−
from flask import Flask, request, jsonify
+
uvicorn main:app --reload
−
from flasgger import Swagger
 
−
 
 
−
app = Flask(__name__)
 
−
swagger = Swagger(app)
 
−
 
 
−
@app.route('/greet', methods=['GET'])
 
−
def greet():
 
−
    """
 
−
    Contoh endpoint yang menyapa pengguna dengan nama yang diberikan.
 
−
    ---
 
−
    parameters:
 
−
      - name: name
 
−
        in: query
 
−
        type: string
 
−
        required: true
 
−
        description: Nama pengguna yang akan disapa.
 
−
    responses:
 
−
      200:
 
−
        description: Berhasil menyapa pengguna.
 
−
        examples:
 
−
          application/json: {"message": "Hello, John!"}
 
−
    """
 
−
    name = request.args.get('name')
 
−
    return jsonify(message=f"Hello, {name}!")
 
−
 
 
−
if __name__ == '__main__':
 
−
    app.run(debug=True)
 
 
```
 
```
−
 
  
−
Dalam contoh ini, parameter `name` ditentukan dalam bagian `parameters` dari docstring, yang memungkinkan Flasgger untuk menghasilkan antarmuka dokumentasi yang interaktif dan informatif.
+
---
  
−
### b. Menggunakan File YAML Eksternal untuk Dokumentasi
+
## 🌐 6. **Akses Swagger UI**
  
−
Selain mendefinisikan dokumentasi dalam docstring, Anda juga dapat menggunakan file YAML eksternal untuk mendokumentasikan endpoint. Berikut adalah langkah-langkahnya:
+
Setelah dijalankan, buka browser dan kunjungi:
  
−
1. **Buat File YAML**: Buat file `greet.yml` dengan konten berikut:
+
```
 +
http://127.0.0.1:8000/docs
 +
```
  
−
  ```yaml
+
Swagger UI akan otomatis tampil dan mendokumentasikan semua endpoint.
−
  ---
 
−
  parameters:
 
−
    - name: name
 
−
      in: query
 
−
      type: string
 
−
      required: true
 
−
      description: Nama pengguna yang akan disapa.
 
−
  responses:
 
−
    200:
 
−
      description: Berhasil menyapa pengguna.
 
−
      examples:
 
−
        application/json: {"message": "Hello, John!"}
 
−
  ```
 
−
 
  
−
2. **Integrasikan File YAML ke dalam Kode**:
+
---
  
−
  ```python
+
## 📝 7. **Akses Redoc (Alternatif UI)**
−
  from flask import Flask, request, jsonify
 
−
  from flasgger import Swagger, swag_from
 
  
−
  app = Flask(__name__)
+
```
−
  swagger = Swagger(app)
+
http://127.0.0.1:8000/redoc
 +
```
  
−
  @app.route('/greet', methods=['GET'])
+
---
−
  @swag_from('greet.yml')
 
−
  def greet():
 
−
      name = request.args.get('name')
 
−
      return jsonify(message=f"Hello, {name}!")
 
  
−
  if __name__ == '__main__':
+
## 🧾 8. **Export Dokumentasi ke JSON atau YAML**
−
      app.run(debug=True)
 
−
  ```
 
−
 
  
−
Pendekatan ini membantu memisahkan logika kode dari dokumentasi, sehingga meningkatkan keterbacaan dan pemeliharaan kode.
+
Kalau kamu butuh file dokumentasi:
  
−
## 3. Mengakses Dokumentasi Swagger
+
### 🔹 JSON:
 +
```
 +
http://127.0.0.1:8000/openapi.json
 +
```
  
−
Setelah mengintegrasikan Flasgger, Anda dapat mengakses dokumentasi interaktif Swagger dengan membuka URL `/apidocs` pada aplikasi Flask Anda. Misalnya, jika aplikasi berjalan secara lokal pada port 5000, Anda dapat mengakses dokumentasi di `http://localhost:5000/apidocs`.
+
### 🔹 YAML (butuh converter, contoh pakai `json2yaml`):
−
 
+
```bash
−
## 4. Praktik Terbaik dalam Mendokumentasikan API
+
pip install json2yaml
−
 
+
curl http://127.0.0.1:8000/openapi.json | json2yaml > openapi.yaml
−
- **Konsistensi**: Pastikan semua endpoint didokumentasikan dengan format yang konsisten untuk memudahkan pemahaman.
+
```
−
 
 
−
- **Kelengkapan**: Sertakan semua parameter, tipe data, dan respons yang mungkin terjadi untuk setiap endpoint.
 
−
 
 
−
- **Pembaruan Berkala**: Selalu perbarui dokumentasi setiap kali ada perubahan pada API untuk menjaga relevansi dan akurasi.
 
−
 
 
−
## 5. Referensi Tambahan
 
−
 
 
−
Untuk informasi lebih lanjut dan contoh penggunaan Flasgger, Anda dapat merujuk ke dokumentasi resmi Flasgger di [GitHub](https://github.com/flasgger/flasgger).
 
−
 
 
−
Dengan mengikuti langkah-langkah di atas, Anda dapat dengan mudah mendokumentasikan API Flask Anda menggunakan Swagger, sehingga memudahkan pengembang lain dalam memahami dan menggunakan API yang Anda buat.
 
  
 +
---
  
 +
Kalau kamu mau integrasi Swagger manual (misalnya pakai Flask atau Express.js), tinggal bilang aja. Tapi buat sekarang, **FastAPI udah auto generate Swagger** tanpa ribet coding dokumentasi manual.
  
−
  - **4.2. Dokumentasi API dengan Swagger**
+
Mau ku buatin template project-nya sekalian dalam folder ZIP? Atau mau lanjut integrasi auth/token dan semacamnya?
−
    - Menggunakan Flask-Swagger untuk mendokumentasikan API yang dibuat.
 
−
    - Contoh: Menambahkan dokumentasi interaktif untuk endpoint yang tersedia.
 
−
    - Referensi: [Tutorial Flask-Swagger](https://github.com/flasgger/flasgger)
 

Revision as of 19:17, 7 April 2025

Oke Dzaq! Di bawah ini adalah panduan lengkap untuk membuat **modul dokumentasi API dengan Swagger** di **Ubuntu 24.04**. Kita akan pakai **FastAPI + Swagger UI** karena simpel dan cocok buat dokumentasi REST API secara otomatis.

---

    1. 🧩 1. **Install Python dan pip**

Ubuntu 24.04 biasanya udah include Python 3. Tapi kita pastikan dulu:

```bash sudo apt update sudo apt install python3 python3-pip -y ```

---

    1. 📦 2. **Buat Virtual Environment (opsional tapi disarankan)**

```bash sudo apt install python3-venv -y python3 -m venv venv source venv/bin/activate ```

---

    1. 🔧 3. **Install FastAPI dan Uvicorn**

```bash pip install fastapi uvicorn ```

---

    1. 📁 4. **Buat File Project: `main.py`**

```python

  1. main.py

from fastapi import FastAPI from pydantic import BaseModel

app = FastAPI(title="Swagger API - Metro TV", version="1.0")

  1. Contoh Model

class Item(BaseModel): 

   name: str
   price: float
   is_offer: bool = None
  1. Route dasar

@app.get("/") def read_root(): 

   return {"message": "Hello, Metro TV"}
  1. Route dengan parameter

@app.get("/items/{item_id}") def read_item(item_id: int, q: str = None): 

   return {"item_id": item_id, "q": q}
  1. POST endpoint

@app.post("/items/") def create_item(item: Item): 

   return {"item": item}

```

---

    1. 🚀 5. **Jalankan API**

```bash uvicorn main:app --reload ```

---

    1. 🌐 6. **Akses Swagger UI**

Setelah dijalankan, buka browser dan kunjungi:

``` http://127.0.0.1:8000/docs ```

Swagger UI akan otomatis tampil dan mendokumentasikan semua endpoint.

---

    1. 📝 7. **Akses Redoc (Alternatif UI)**

``` http://127.0.0.1:8000/redoc ```

---

    1. 🧾 8. **Export Dokumentasi ke JSON atau YAML**

Kalau kamu butuh file dokumentasi:

      1. 🔹 JSON:

``` http://127.0.0.1:8000/openapi.json ```

      1. 🔹 YAML (butuh converter, contoh pakai `json2yaml`):

```bash pip install json2yaml curl http://127.0.0.1:8000/openapi.json | json2yaml > openapi.yaml ```

---

Kalau kamu mau integrasi Swagger manual (misalnya pakai Flask atau Express.js), tinggal bilang aja. Tapi buat sekarang, **FastAPI udah auto generate Swagger** tanpa ribet coding dokumentasi manual.

Mau ku buatin template project-nya sekalian dalam folder ZIP? Atau mau lanjut integrasi auth/token dan semacamnya?

Retrieved from "https://onnocenter.or.id/wiki/index.php?title=Dokumentasi_API_dengan_Swagger&oldid=72457"