Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 36 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,55 @@
# API Explorer
<div align="center">
<div align="center">
<img width="128" alt="logo" src="https://github.com/user-attachments/assets/9c45923e-081f-461c-b3d3-44071afb34be" />
</div>
<h2>Frappe OpenAPI</h2>
A Frappe app to <strong>generate</strong> and <strong>visualize</strong> whitelisted APIs with interactive Swagger UI documentation.
</div>
<br>
<div align="center">
<img width="1920" height="965" alt="image" src="https://github.com/user-attachments/assets/f441732b-c903-4005-97c2-c7e3afcd330f" />
</div>

A beautiful Frappe app to **generate** and **visualize** whitelisted APIs with interactive Swagger UI documentation.
## Features

- Automatically generates OpenAPI (Swagger) JSON files for all installed Frappe apps.
- Responsive Swagger UI portal with sidebar app selection.
- Displays API endpoints, parameters, sample requests, and responses.

---
<img width="1339" height="729" alt="Screenshot 2025-07-25 at 10 09 30 AM" src="https://github.com/user-attachments/assets/90279305-347f-4bd3-977a-c7910f0c107b" />

## Installation

Run the following commands inside your bench directory:

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

- Automatically generates OpenAPI (Swagger) JSON files for all installed Frappe apps.
- Responsive Swagger UI portal with sidebar app selection.
- Displays API endpoints, parameters, sample requests, and responses.
> For a detailed installation guide and advanced configuration, visit the [Wiki](https://github.com/rtCamp/frappe-openapi/wiki).

---

## How to Use

1. **Install the app** in your Frappe site.
2. **Run `bench migrate`** to apply changes and update your site.
3. **Run the OpenAPI generator**.
4. **Access the API Explorer UI** at `/docs` or `/redoc`.
5. **Select an app** from the sidebar to view its API documentation.
6. **Try out endpoints** directly from the Swagger UI.
1. **Install the app** using the steps above.
2. **Access the API Explorer UI** at `/docs`.
3. **Select an app** from the sidebar to view its API documentation.
4. **Try out endpoints** directly from the Swagger UI.

---

## Whitelisting Functions for API Explorer

To ensure your APIs are documented correctly:

- **Whitelist your function** using `@frappe.whitelist()` or in `hooks.py`.
- **Add a detailed Python docstring** to your function, including:
- **Description** of what the endpoint does.
- **Sample Response** format (JSON).
- **Whitelist your function** using `@frappe.whitelist()`.
- **Add a Python docstring** that includes:
- A **description** of what the endpoint does.
- A **sample response** in JSON format.

**Example:**

Expand All @@ -53,13 +69,14 @@ def create_customer(name, email):
```

**Guidelines:**

- Always describe the endpoint's purpose.
- Include clear sample response blocks.
- Keep examples concise and relevant.
- These doc comments are parsed and shown in the API Explorer UI.
- These docstrings are parsed and shown in the API Explorer UI.

---

## License

agpl-3.0
[AGPL-3.0](LICENSE)
2 changes: 1 addition & 1 deletion frappe_openapi/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "1.0.0"
__version__ = "1.0.1"
Empty file added frappe_openapi/api/__init__.py
Empty file.
Loading
Loading