📝 Add Docs for setting up automatic OpenAPI docs

0xsirsaif · Nov 7, 2024 · ce1411a · ce1411a
1 parent ac954b9
commit ce1411a
Show file tree

Hide file tree

Showing 2 changed files with 142 additions and 18 deletions.
diff --git a/docs/openapi_docs.md b/docs/openapi_docs.md
@@ -0,0 +1,97 @@
+# Setting Up OpenAPI Documentation in Frappe
+
+This guide explains how to set up automatic OpenAPI documentation using Swagger UI in your Frappe application.
+
+## 1. Create Portal Page Directory
+
+```bash
+mkdir -p templates/pages/docs/
+```
+
+`/docs` is the directory where the Swagger UI will be served from `http://{site}.com/docs`. You can change this to any directory you want.
+
+## 2. Create `index.html` inside the `docs` directory, add the following code:
+
+```html
+{% extends "templates/web.html" %}
+
+{% block title %} Frappe API {% endblock %}
+
+{%- block header -%}
+<meta charset="UTF-8">
+  <title>Frappe API</title>
+  <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
+  <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.9.4/swagger-ui.css" >
+  <style>
+    html
+    {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *,
+    *:before,
+    *:after
+    {
+      box-sizing: inherit;
+    }
+    body {
+      margin:0;
+      background: #fafafa;
+    }
+  </style>
+{% endblock %}
+
+
+{%- block page_content -%}
+<div id="swagger-ui"></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.9.4/swagger-ui-bundle.js"> </script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.9.4/swagger-ui-standalone-preset.js"> </script>
+<script>
+  var spec = JSON.parse('{{ data | tojson | safe }}');
+  const ui = SwaggerUIBundle({
+    spec: spec,
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout",
+    requestInterceptor: (request) => {
+      request.headers['X-Frappe-CSRF-Token'] = frappe.csrf_token;
+      return request;
+    }
+  })
+</script>
+{% endblock %}
+
+```
+
+## 3. Create `index.py` inside the `docs` directory, with the following code:
+
+```python
+# import your FrappeAPI app
+from your_app.apis import app
+
+# openapi() is a method that returns the auto-generated OpenAPI schema
+# You could add more context to the ctx object to pass additional data to the template
+# For example, you could add a "title" or "description" to the API docs
+def get_context(ctx):
+    ctx.data = app.openapi()
+```
+
+## 4. Access Documentation
+
+After setting up the files:
+
+1. Restart your Frappe server
+2. Access your documentation at: `http://your-site/docs`
+
+## Notes
+
+- The documentation will automatically update when you modify your API endpoints
+- The CSRF token is automatically included in API requests through the request interceptor
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,40 +1,67 @@
 site_name: FrappeAPI
 site_url: https://0xsirsaif.github.io/frappe-api/
+site_author: Muhammad Saif
+site_description: A FastAPI wrapper for Frappe Framework
+repo_name: 0xsirsaif/frappe-api
+repo_url: https://github.com/0xsirsaif/frappe-api
+edit_uri: https://github.com/0xsirsaif/frappe-api/tree/main/docs
+
+
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/0xsirsaif/frappe-api
+    - icon: fontawesome/brands/twitter
+      link: https://x.com/0xsirsaif
+
 theme:
   name: material
-  palette:
-    primary: deep purple
-    accent: deep purple
   features:
     - navigation.instant
     - navigation.tracking
-    - navigation.tabs
     - navigation.sections
     - navigation.expand
     - toc.integrate
     - content.code.copy
+  palette:
+    # Palette for light mode
+    - scheme: default
+      primary: deep purple
+      accent: deep purple
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to dark mode
 
-repo_name: 0xsirsaif/frappe-api
-repo_url: https://github.com/0xsirsaif/frappe-api
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: deep purple
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to light mode
+
 
 nav:
-  - FrappeAPI: index.md
+  - Introduction: index.md
+  - OpenAPI Docs: openapi_docs.md
   - Roadmap: roadmap.md
 
 markdown_extensions:
+  - admonition
+  - pymdownx.details
   - pymdownx.superfences
+  - attr_list
+  - md_in_html
   - pymdownx.tabbed:
       alternate_style: true
-  - admonition
-  - pymdownx.details
-  - pymdownx.tasklist:
-      custom_checkbox: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.highlight:
+      anchor_linenums: true
   - toc:
       permalink: true
-
-extra:
-  social:
-    - icon: fontawesome/brands/github-alt
-      link: https://github.com/0xsirsaif/frappe-api
-    - icon: fontawesome/brands/twitter
-      link: https://x.com/0xsirsaif
+  - pymdownx.tasklist:
+      custom_checkbox: true