Automatically Expose Interactive API Documentation

Enable interactive API documentation automatically for web applications.

1️⃣ Description of the idea

Automatically enable a default API documentation endpoint—such as /docs or /apidocs—when a new %CSP.REST-based dispatch class is created. This endpoint would serve an interactive OpenAPI (Swagger) UI, generated from the class’s OpenAPI-compliant definitions or annotations.

This behavior would mirror other automated configurations, like how enabling "Use JWT Authentication" in a web application adds /login and /logout endpoints automatically.

2️⃣ Who is the target audience?

API developers and backend developer creating RESTful services in IRIS and it enforces the Spec-First approach by default and well as for legacy web application.

Frontend and mobile developers who need to explore and test available APIs

QA and DevOps teams validating API behavior directly by accessing this interactive documentation

3️⃣ What problem does it solve?

This implementation enables

• Making it easier to onboard, test, and explore APIs

• Reducing manual setup

• Ensuring documentation is always in sync

4️⃣ How does this impact the efficiency, stability, reliability, etc., of the product?

• Developers get instant access to usable, accurate API documentation without additional configuration.

• Greatly improves the developer experience for both API creators, consumers and QA.

• Reduces risk of misconfigured or outdated API docs.

• Lowers overhead for managing external documentation tools or syncing specs manually

5️⃣ Provide a specific use case or scenario that illustrates how this idea could be used in practice

creates a REST API for patient data using a new %CSP.REST-based dispatch class named MyApp.PatientAPI.

Current Workflow:

Legacy Approach
To document and test it, they must:

• Manually write an OpenAPI spec

• Set up a Swagger UI (or similar tool)

• Ensure changes in endpoints/methods are reflected in the spec

Sepc-First Approach

• use Spec-First approach and generate the dispatch by swagger

• Set up a Swagger UI and test

With Automatic /docs Endpoint:
Upon creating the dispatch class in IRIS automatically

• Generates an OpenAPI schema from defined routes and method signatures - for legacy REST implementation

• Exposes an interactive Swagger UI at /docs (e.g., /myapp/patientapi/docs)

• Updates the documentation in real-time as the class evolves

Result:

• Instant, accurate, and interactive documentation and Faster testing, onboarding, and feedback loops

• Improved developer and integration partner satisfaction