How do I structure a large API where using namespaces in generated client code would be ideal?

[tibbe]

We have a large API defined in Python using Pydantic/FastAPI. On the Python side the schemas/paths are neatly structure into separate python modules (e.g. users.py for /users and all its schemas). We'd like to generate an OpenAPI client* (e.g. for TypeScript) that is similarly well organized but it doesn't seem possible to preserve enough information in the OpenAPI spec such that a client that uses namespaces can be generated.

• Is it possible to generate clients using namespaces?
  • What approach would be suitable? Relying on tags? Parsing the path and generating namespaces from e.g. the last path component?
• How do people manage large APIs and clients generated for such?

* I'm fine writing my own client generator. The issue is more whether OpenAPI is too lossy to be able to do so.

[handrews]

I think most people would use tags for this sort of thing. It's then up to tools to define how they can use tags, and whether you need to do some sort of configuration to distinguish between (for example) namespacing tags vs other uses of tags. But tags is how people group operations in documentation, for example.

[handrews]

No further comments in several months; closing. If there's a desire to follow-up further, I'd suggest looking at:

• The OAS 3.x issues labeled as metadata, which include tag-related issues
• OAS 4.0 "Moonwalk" discussions:
  • Better tags sig-moonwalk#67
  • Resource oriented sig-moonwalk#30 (has some discussion of hierarchy)