Public API: No official API documentation — docs URLs return 404

[pneumatic-seidler]

Summary

This is an improvement proposal. If after review it is deemed unnecessary, this issue can be closed.

Problem

There is no publicly accessible, comprehensive API documentation for the Pneumatic Public API. Common documentation URLs return HTTP 404:

• https://api.pneumatic.app/docs/ → 404
• https://www.pneumatic.app/api-docs/ → 404
• https://my.pneumatic.app/api/docs/ → lists endpoint URLs only, with no request/response schemas, no parameter descriptions, no examples

The primary source of truth is the GitHub Wiki, which contains pages for individual endpoints. However:

1. Incomplete information — e.g., wiki documents user fields as accepting "User ID (integer)" when the backend actually requires email addresses (see Public API: User-type fields only accept email strings, not numeric user IDs #123)
2. Intermittent availability — wiki pages sometimes fail to load
3. No index page — there is no single page linking all Public API wiki articles
4. Partial schemas — request/response JSON structures are only partially documented

Impact

Developers integrating with the Pneumatic API must reverse-engineer the API by reading backend source code (urls.py, serializers, views) and through trial-and-error. This significantly increases integration time.

Proposed Solutions

Option A (Recommended) — Auto-generated OpenAPI/Swagger docs:
Django REST Framework supports automatic schema generation via drf-spectacular or drf-yasg. Host at a stable URL like https://api.pneumatic.app/docs/ with request bodies, response schemas, auth requirements, and example payloads.

Option B — Improve the GitHub Wiki:

• Create a comprehensive index page linking all API endpoints
• Add complete request/response JSON examples to each page
• Fix known inaccuracies (e.g., user field format)
• Add a "Quick Start" guide

Option C — Both:
Auto-generated Swagger for accuracy + curated wiki guides for tutorials and walkthroughs.

Expected Outcome

A developer can find, read, and follow API documentation to successfully integrate with the Pneumatic API without needing access to the backend source code.