Publish a live OpenAPI specification

[mamift]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• Pleas do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing?

I want to create my own client for the dify API in C# and TypeScript. I see there are Java, Ruby and Go client libraries already created, but they do not seem to be based on an OpenAPI specification; i.e. they're hand written. I think this is a mistake. What is more useful for programmers these days is to take a specification like an OpenAPI spec, and use that to create a client library in a language of their own choice.

The reasoning is: vendors should not bother creating language-specific client libraries for their APIs or services anymore as it is too much hassle to:

• manually write all the connecting/glue code, which is idiomatically different in each language
• support the different type systems used by different languages
• support the package and dependency management systems that each language has

What should be done is: vendors should publish specifications that allow any programmer of any language to create their own clients using code generators that take the specification as input and generates scaffolding code that can be used to create a client library in a language of their own choosing.

In the case of OpenAPI, a very popular tool for generating clients is the openapi-generator-cli. It supports generating client code for about 24+ languages.

2. Describe the feature you'd like to see

Publish an OpenAPI specification for the entirety of the dify API surface, from the dataset API, to the chatting/workflow API.

And ideally it should be available in app, like how currently, the {DIFY_APP_URL]/app/{APP_UID}/develop URL is used to display the documentation for a custom app's API.

A good example of what I'm talking about is JIRAs API: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#about

They provide an OpenAPI spec.

3. How will this feature improve your workflow or experience?

I can generate C# and TypeScript code for dify API. And others will be able to create client code in nearly any programming language of their choice using a code generator like openapi-generator.

This would also mean the dify maintainers would no longer need to maintain the Java, Ruby and Go client libraries for others to use; just point future devs to the the OpenAPI spec and they can create their own libraries!

Alternatively, if you wanted to keep your own 'official' client libraries for a select few languages, you can just use the code generator to automatically update official client libraries whenever the OpenAPI spec changes; all you would need to do is just re-run the code generator against an updated OpenAPI spec.

4. Additional context or comments

Doing this would also provide the benefit of being able to import the spec into tools like Postman.

5. Can you help us with this feature?

• I am interested in contributing to this feature.

[takatost]

Thank you so much for your suggestion!
We have realized that and are planning to switch from flask-restful to flask-restx to support the retrieval and export of OpenAPI Schema. After that, we can continue to use tools like fern or stainlessapi to automatically generate SDKs for various languages. If you're interested, you can continue developing based on the branch where #3920 is located. We would really appreciate it! 🙏