Home

Frappe OpenAPI

A Frappe app to generate and visualize whitelisted APIs with interactive Swagger UI documentation.

---

What is Frappe OpenAPI?

Frappe OpenAPI is a Frappe app that automatically introspects all installed apps on your site, discovers every @frappe.whitelist() function, and generates a standard OpenAPI 3.0 JSON specification for each one.

The generated specs are served through a built-in Swagger UI at /docs, giving developers a clean, interactive portal to:

• Browse all documented API endpoints across every installed app.
• View request parameters, request body schemas, and expected response structures.
• Execute live test requests directly from the browser — no external tool needed.

Key Features:

• Automatically generates OpenAPI JSON for all installed Frappe apps on every bench migrate.
• Responsive Swagger UI with a sidebar for switching between apps.
• Parses Python docstrings to extract endpoint descriptions and sample responses.
• Configurable — choose which modules are included via OpenAPI Settings.

---

Installation

Run the following commands inside your bench directory:

bench get-app https://github.com/rtCamp/frappe-openapi.git
bench install-app frappe_openapi
bench migrate
bench restart

---

Configuration

After installation, configure which modules are documented:

1. Navigate to OpenAPI Settings in your Frappe site:

   /app/openapi-settings/OpenAPI%20Settings
   

2. Select the modules for which APIs should be generated.
3. Save the settings.
4. Run bench migrate to regenerate the OpenAPI specs with your updated selection.

---

Accessing API Documentation

Open the Swagger UI at:

/docs

From the UI:

1. Select a module from the left sidebar.
2. Browse available endpoints grouped by module.
3. Expand an endpoint to view:
   • Request parameters
   • Request body (if applicable)
   • Response structure
4. Click Try it out to execute a live request directly from the browser.

---

Whitelisting Functions

For your API endpoints to appear in the documentation, they must be:

1. Decorated with @frappe.whitelist().
2. Documented with a Python docstring that includes a description and a sample response.

Example:

@frappe.whitelist()
def create_customer(name, email):
    """
    Create a new customer.

    Response:
    {
        "status": "success",
        "customer_id": "CUS12345"
    }
    """
    # Your implementation here

Guidelines:

• Always describe what the endpoint does.
• Include a realistic sample response block.
• Keep examples concise and relevant.

---

License

AGPL-3.0