Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Create methods to register all component objects #245
Currently, definitions can be registered to be referenced to in the spec.
The spec allows to register other objects like parameters or responses.
Some of them also exist in OpenAPI 2. Search for "Swagger Object" in https://swagger.io/specification/v2/.
We'd rather get this right with all those objects in mind rather than address them independently each time everyone needs one of them.
It should be easy to create methods to register each object type. Or should we create a single method and pass the type as argument (and deprecate
Then it's less obvious how to help the developer to use references. Referencing schema definition is automatic. Referencing responses probably wouldn't be, so the user would have to enter the reference response name. Ideally, we'd provide a function that at least takes care of the
For instance, 3556849 added the possibility to pass parameters a while ago.
We'd need to either do the same with each component type (response, security, etc.), or create a single method to manage them all. Since it's less than a ten of them, a method for each is reasonable. Besides, it makes it easier to do step-by-step.
Also, there should be hooks to allow plugins to provide helpers. For instance, there could be parameter helpers so that marshmallow schemas can be parsed when registered as parameters, response helpers, header helpers,...
Referencing could be done as was done for parameters: the developer passes the parameter name as a string and the
Overall, this issue is two-fold:
Currently, existing methods are
It would be nice to have consistent naming.
Should it be
Or a generic
#305 proposes another approach: use a
From developer perspective, it allows to separate those methods rather than have an APISpec class with many methods. From user perspective, it is more verbose (needs to add
We have many possibilities:
No prefix (not explicit enough IMHO):
Components + prefix (e.g. add):
Definitions were renamed as schemas in v3, so we could use, schema, or definition, or both.
I don't like the common method + string parameter approach as using a string is weird and I don't like the idea of having a slingle signature for methods with different parameters. But I like the consistency brought by the use of a common term (here, "components") in all methods.
It is this last approach that led me to adding a components class to use methods with some sort of components namespace:
Overall, my best choices are "add_xxx" with or without components class.
I'm not sure there is an interest in separating components (definitions/schemas, parameters, responses) and other stuff (tags, paths,...).
@sloria, feedback welcome. This design choice is the only breaking part of the change. Once this is done, it does not block 1.0 anymore and other components can be added later in further non-breaking changes.
Anyone willing to contribute can easily add methods to register other component types. I don't think they'll need plugin helpers. Just pay attention to OpenAPI v2 vs. v3 differences.
(At this point, I'm tempted to add that help wanted label back, or ready to claim, or any label meaning it is easy and anyone is welcome to work on this.)
List of components
When adding a component adder method, it would be nice to also update
(TODO: resolve headers refs in response in