Dokumentasi API dengan Swagger: Difference between revisions

From OnnoCenterWiki
Jump to navigationJump to search
← Older edit
Unknown user (talk)
No edit summary
No edit summary
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
# Modul 4.2: Dokumentasi API dengan Swagger
Kita akan pakai '''FastAPI + Swagger UI''' karena simpel dan cocok buat dokumentasi REST API secara otomatis.


## Pendahuluan
==Install Python dan pip==
Ubuntu 24.04 biasanya udah include Python 3. Tapi kita pastikan dulu:


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.
sudo apt update
sudo apt install python3 python3-pip -y


## 1. Instalasi dan Konfigurasi Flasgger
==Buat Virtual Environment (opsional tapi disarankan)==


### a. Instalasi Flasgger
sudo apt install python3-venv -y
python3 -m venv venv
source venv/bin/activate


Pastikan Anda telah menginstal Flask. Jika belum, Anda dapat menginstalnya dengan perintah berikut:
==Install FastAPI dan Uvicorn==


pip install fastapi uvicorn


```bash
==Buat File Project: `main.py`==
pip install Flask
```


Selanjutnya, instal Flasgger menggunakan pip:
# main.py
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI(title="Swagger API - Metro TV", version="1.0")
# Contoh Model
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None
# Route dasar
@app.get("/")
def read_root():
    return {"message": "Hello, Metro TV"}
# Route dengan parameter
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}
# POST endpoint
@app.post("/items/")
def create_item(item: Item):
    return {"item": item}


==Jalankan API==


```bash
uvicorn main:app --reload
pip install flasgger
```


### b. Konfigurasi Dasar Flasgger
==Akses Swagger UI==


Setelah instalasi, Anda dapat mengintegrasikan Flasgger ke dalam aplikasi Flask Anda. Berikut adalah contoh dasar konfigurasi Flasgger:
Setelah dijalankan, buka browser dan kunjungi:


http://127.0.0.1:8000/docs


```python
Swagger UI akan otomatis tampil dan mendokumentasikan semua endpoint.
from flask import Flask
from flasgger import Swagger


app = Flask(__name__)
==Akses Redoc (Alternatif UI)==
swagger = Swagger(app)


@app.route('/hello', methods=['GET'])
http://127.0.0.1:8000/redoc
def hello():
    """
    Endpoint untuk menyapa pengguna.
    ---
    responses:
      200:
        description: Berhasil menyapa pengguna.
    """
    return "Hello, World!"


if __name__ == '__main__':
==Export Dokumentasi ke JSON atau YAML==
    app.run(debug=True)
```


Dalam contoh di atas, Flasgger secara otomatis menghasilkan dokumentasi untuk endpoint `/hello` berdasarkan docstring yang disediakan.
Kalau kamu butuh file dokumentasi:


## 2. Menambahkan Dokumentasi Interaktif untuk Endpoint
'''JSON:'''


### a. Menggunakan Docstring untuk Dokumentasi
http://127.0.0.1:8000/openapi.json


Flasgger memungkinkan Anda untuk mendokumentasikan endpoint langsung dalam docstring fungsi. Berikut adalah contoh bagaimana menambahkan dokumentasi untuk endpoint dengan parameter:
'''YAML (butuh converter, contoh pakai `json2yaml`):'''


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


```python
==Catatan:==
from flask import Flask, request, jsonify
from flasgger import Swagger


app = Flask(__name__)
* Kita dapat integrasi Swagger manual (misalnya pakai Flask atau Express.js).
swagger = Swagger(app)
* Saat ini, '''FastAPI sudah auto generate Swagger''' tanpa ribet coding dokumentasi manual.


@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__':
==Pranala Menarik==
    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.
* [[Web Programming]]
 
### b. Menggunakan File YAML Eksternal untuk Dokumentasi
 
Selain mendefinisikan dokumentasi dalam docstring, Anda juga dapat menggunakan file YAML eksternal untuk mendokumentasikan endpoint. Berikut adalah langkah-langkahnya:
 
1. **Buat File YAML**: Buat file `greet.yml` dengan konten berikut:
 
  ```yaml
  ---
  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
  from flask import Flask, request, jsonify
  from flasgger import Swagger, swag_from
 
  app = Flask(__name__)
  swagger = Swagger(app)
 
  @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__':
      app.run(debug=True)
  ```
 
Pendekatan ini membantu memisahkan logika kode dari dokumentasi, sehingga meningkatkan keterbacaan dan pemeliharaan kode.
 
## 3. Mengakses Dokumentasi Swagger
 
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`.
 
## 4. Praktik Terbaik dalam Mendokumentasikan API
 
- **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.
 
 
 
  - **4.2. Dokumentasi API dengan Swagger**
    - 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)

Latest revision as of 01:09, 8 April 2025

Kita akan pakai FastAPI + Swagger UI karena simpel dan cocok buat dokumentasi REST API secara otomatis.

Install Python dan pip

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

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

Buat Virtual Environment (opsional tapi disarankan)

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

Install FastAPI dan Uvicorn

pip install fastapi uvicorn

Buat File Project: `main.py`

# main.py

from fastapi import FastAPI
from pydantic import BaseModel

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

# Contoh Model
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None 

# Route dasar
@app.get("/")
def read_root():
    return {"message": "Hello, Metro TV"}

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

# POST endpoint
@app.post("/items/")
def create_item(item: Item):
    return {"item": item}

Jalankan API

uvicorn main:app --reload

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.

Akses Redoc (Alternatif UI)

http://127.0.0.1:8000/redoc

Export Dokumentasi ke JSON atau YAML

Kalau kamu butuh file dokumentasi:

JSON: 

http://127.0.0.1:8000/openapi.json

YAML (butuh converter, contoh pakai `json2yaml`): 

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

Catatan:

  • Kita dapat integrasi Swagger manual (misalnya pakai Flask atau Express.js).
  • Saat ini, FastAPI sudah auto generate Swagger tanpa ribet coding dokumentasi manual.


Pranala Menarik

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