Support the Spec/API/Design-first approach

[greyli]

This project currently only supports the Code-first approach, in other words, it generates the OpenAPI spec from your code and keeps the spec in sync with your code afterward. While the Spec-first approach allows you to write the spec first, when every detail of the API is discussed and confirmed, you start to code based on the spec. Both approaches have their own pros and cons. Although Code-first seems quite convenient and popular, I still hope to support the Spec-first approach for APIFlask, and it's the recommended approach by the OpenAPI initiative.

Ideas

A good starting point is to support for a Semi-Spec-first approach:

• Provide a codegen tool, generates the skeleton code (routes, schemas, models, etc.) from an existing spec.
• After the generation, turns to the Code-first approach. In this way, the spec can easily keep sync with the code.

After this, we can start to think of supporting the real Spec-first workflow. TBH, I don't quite familiar with the Spec-first approach, especially:

• How to keep the code and spec in sync? If a user uses the codegen tool, after the code is generated, if we change a field name in the spec, then we have to update the code manually?
• If the validation is based on the spec and JSON schema, how to add pre/post procession hooks for the input/output data?
• What's the ideal workflow?
• What and how much the framework should get involved?

Before these happen, maybe we can recommend the user to use Connexion in the docs since it's now back to the maintenance status (spec-first/connexion#1365).

Resources

See a relevant discussion here.

Learning resources checklist:

• Contract-First API Development Using The OpenAPI Specification (Swagger) - PyCon 2017
• Connexion's source code
• Connexion's documentation

[Yongbeom-Kim]

Hey @greyli, just came across this from the OpenAPI Generating page. It's been three years since you've created the issue, but I'm still quite interested in APIFlask supporting this. Wondering if your views on this have changed since you've created the post?