chore: add script to generate openapi v2 json and add in README #35474

[asukaminato0721]

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Summary

fix #35474

Screenshots

Before	After
...	...

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran make lint && make type-check (backend) and cd web && pnpm exec vp staged (frontend) to appease the lint gods

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-04-22 03:43:24.730744063 +0000
+++ /tmp/pyrefly_pr.txt	2026-04-22 03:43:12.181685087 +0000
@@ -82,6 +82,10 @@
   --> core/tools/utils/web_reader_tool.py:66:35
 ERROR `list[Never]` is not assignable to attribute `tools` with type `Never` [bad-assignment]
    --> core/tools/workflow_as_tool/provider.py:238:26
+ERROR `str` is not assignable to attribute `STORAGE_TYPE` with type `Literal['aliyun-oss', 'azure-blob', 'baidu-obs', 'clickzetta-volume', 'google-storage', 'huawei-obs', 'local', 'oci-storage', 'opendal', 's3', 'supabase', 'tencent-cos', 'volcengine-tos']` [bad-assignment]
+  --> dev/generate_swagger_specs.py:53:32
+ERROR Object of class `object` has no attribute `model` [missing-attribute]
+  --> dev/generate_swagger_specs.py:93:13
 ERROR Cannot index into `Literal['']` [bad-index]
   --> extensions/storage/huawei_obs_storage.py:27:23
 ERROR Cannot index into `Literal['']` [bad-index]

[asukaminato0721]

known limitation:

will have unknown since openapi v2 don't have anyOf which is v3-only

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-04-22 03:53:25.146338620 +0000
+++ /tmp/pyrefly_pr.txt	2026-04-22 03:53:14.228373295 +0000
@@ -82,6 +82,8 @@
   --> core/tools/utils/web_reader_tool.py:66:35
 ERROR `list[Never]` is not assignable to attribute `tools` with type `Never` [bad-assignment]
    --> core/tools/workflow_as_tool/provider.py:238:26
+ERROR Object of class `object` has no attribute `model` [missing-attribute]
+  --> dev/generate_swagger_specs.py:95:13
 ERROR Cannot index into `Literal['']` [bad-index]
   --> extensions/storage/huawei_obs_storage.py:27:23
 ERROR Cannot index into `Literal['']` [bad-index]

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-04-22 03:55:43.667215074 +0000
+++ /tmp/pyrefly_pr.txt	2026-04-22 03:55:32.557126345 +0000
@@ -82,6 +82,10 @@
   --> core/tools/utils/web_reader_tool.py:66:35
 ERROR `list[Never]` is not assignable to attribute `tools` with type `Never` [bad-assignment]
    --> core/tools/workflow_as_tool/provider.py:238:26
+ERROR Object of class `Swagger` has no attribute `_anonymous_inline_models` [missing-attribute]
+  --> dev/generate_swagger_specs.py:77:13
+ERROR Object of class `object` has no attribute `model` [missing-attribute]
+  --> dev/generate_swagger_specs.py:96:13
 ERROR Cannot index into `Literal['']` [bad-index]
   --> extensions/storage/huawei_obs_storage.py:27:23
 ERROR Cannot index into `Literal['']` [bad-index]

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-04-22 04:24:43.023643616 +0000
+++ /tmp/pyrefly_pr.txt	2026-04-22 04:24:32.193630869 +0000
@@ -82,6 +82,8 @@
   --> core/tools/utils/web_reader_tool.py:66:35
 ERROR `list[Never]` is not assignable to attribute `tools` with type `Never` [bad-assignment]
    --> core/tools/workflow_as_tool/provider.py:238:26
+ERROR Object of class `Swagger` has no attribute `_anonymous_inline_models` [missing-attribute]
+  --> dev/generate_swagger_specs.py:77:13
 ERROR Cannot index into `Literal['']` [bad-index]
   --> extensions/storage/huawei_obs_storage.py:27:23
 ERROR Cannot index into `Literal['']` [bad-index]

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-04-22 04:26:49.621271353 +0000
+++ /tmp/pyrefly_pr.txt	2026-04-22 04:26:39.424278145 +0000
@@ -82,6 +82,8 @@
   --> core/tools/utils/web_reader_tool.py:66:35
 ERROR `list[Never]` is not assignable to attribute `tools` with type `Never` [bad-assignment]
    --> core/tools/workflow_as_tool/provider.py:238:26
+ERROR Object of class `Swagger` has no attribute `_anonymous_inline_models` [missing-attribute]
+  --> dev/generate_swagger_specs.py:77:13
 ERROR Cannot index into `Literal['']` [bad-index]
   --> extensions/storage/huawei_obs_storage.py:27:23
 ERROR Cannot index into `Literal['']` [bad-index]

[Copilot]

Pull request overview

Adds a lightweight developer script to export the backend’s Flask-RESTX Swagger (OpenAPI v2) JSON specs, plus documentation and a unit test to validate the export output.

Changes:

• Added api/dev/generate_swagger_specs.py to generate Swagger 2.0 JSON for console/web/service APIs without starting the full backend.
• Added a unit test covering JSON generation and basic schema expectations.
• Updated api/README.md with instructions to run the generator and convert to TypeScript.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

File	Description
api/dev/generate_swagger_specs.py	New standalone script to mount API blueprints and write Swagger v2 JSON specs to disk.
api/tests/unit_tests/commands/test_generate_swagger_specs.py	New unit test validating that the generator writes the expected spec files and that they look like Swagger v2.
api/README.md	Documents how to run the generator and a manual TS conversion step.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wylswz]

Tested locally, works fine.

[wylswz]

It would be nice if APIs were grouped by domains.

[asukaminato0721]

It would be nice if APIs were grouped by domains.

In next pr will do it