WebSocket APIs offer a powerful way to create real-time, interactive applications by enabling bidirectional communication between clients and servers. Documenting these APIs is crucial for developers to understand and utilize them effectively. Swagger (now known as OpenAPI) is a widely used framework for API documentation, but it primarily focuses on HTTP-based APIs. This article will explore how to document WebSocket APIs using Swagger in a Python environment.
Understanding WebSocket APIs
Before diving into the documentation process, let's briefly understand what WebSocket APIs are. WebSockets provide a full-duplex communication channel over a single, long-lived connection between a client and a server. This is ideal for applications that require real-time updates, such as chat applications, online gaming, live sports updates, and collaborative platforms.
Setting Up Swagger for Python
Swagger can be integrated with Python applications using tools like Flask and FastAPI. Both frameworks have extensive support for Swagger documentation out of the box, though they are traditionally used for HTTP APIs. To start, you'll need to install the required libraries:
pip install fastapi uvicornCreating a WebSocket API with FastAPI
Here's a simple WebSocket API built with FastAPI:
from fastapi import FastAPI, WebSocket
from fastapi.responses import HTMLResponse
app = FastAPI()
html = """
<!DOCTYPE html>
<html>
<head>
<title>WebSocket Test</title>
</head>
<body>
<h1>WebSocket Test</h1>
<form id="form">
<input type="text" id="messageInput" autocomplete="off"/>
<button>Send</button>
</form>
<ul id="messages"></ul>
<script>
const form = document.getElementById('form');
const input = document.getElementById('messageInput');
const messages = document.getElementById('messages');
const ws = new WebSocket('ws://localhost:8000/ws');
ws.onmessage = function(event) {
const li = document.createElement('li');
li.textContent = event.data;
messages.appendChild(li);
};
form.addEventListener('submit', function(event) {
event.preventDefault();
ws.send(input.value);
input.value = '';
});
</script>
</body>
</html>
"""
@app.get("/")
async def get():
return HTMLResponse(html)
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
await websocket.accept()
while True:
data = await websocket.receive_text()
await websocket.send_text(f"Message text was: {data}")
This example sets up a simple WebSocket server with a basic HTML client to send and receive messages.
Documenting the WebSocket API with Swagger
Swagger is primarily used for documenting RESTful APIs, but we can still leverage its features to provide comprehensive documentation for our WebSocket endpoints.
Creating an OpenAPI Specification
To document our WebSocket API, we can include details in the OpenAPI specification provided by FastAPI. Although OpenAPI does not natively support WebSocket, we can add descriptions and examples in the documentation.
from fastapi.openapi.utils import get_openapi
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="WebSocket API",
version="1.0.0",
description="This is a simple WebSocket API",
routes=app.routes,
)
openapi_schema["paths"]["/ws"] = {
"get": {
"summary": "WebSocket connection",
"description": "Connect to the WebSocket server. Send a message and receive a response.",
"responses": {
"101": {
"description": "Switching Protocols - The client is switching protocols as requested by the server.",
}
}
}
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
In this example, we override FastAPI's default OpenAPI generation to include a description of our WebSocket endpoint. This approach provides developers with a clear understanding of how to interact with the WebSocket server.
Running and Testing the Documentation
To run the FastAPI application with the custom documentation:
uvicorn your_app:app --reloadVisit http://localhost:8000/docs to see the interactive Swagger UI with your custom documentation.
Output
.png)