Dokumentasi API dengan Swagger: Difference between revisions

From OnnoCenterWiki
Jump to navigationJump to search
← Older editNewer edit →
Unknown user (talk)
No edit summary
No edit summary
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 12: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://lms.onnocenter.or.id/wiki/index.php?title=Dokumentasi_API_dengan_Swagger&oldid=72457"