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
parameter name and in required for referenced parameter #463
Hi, I have just updated to version 2.0.0 of apispec and I've seen a whole load of new error messages
and then reference it in the doc string:
Now I need to add 'in' and 'name' into the docstring for this parameter but I have already specified the location and name in the top level definition. I see that there has been recent activity in this area so apologies if this is something that is in hand - I just wanted to raise it in case it was overlooked.
This is probably something we overlooked. Sorry about that and thanks for reporting.
On second thought, I don't think my suggestion above will make it work. I'm pretty sure, however, that apispec expects only a ref name, not the whole ref component path, as it handles the path itself (including OASv2 / OASv3 differences) but that is another story.
My suggestion might solve your case, I can't tell as I'm not sure what YAML parser does, but there's definitely an issue.
On the first call, string references are changed into dictionaries, and on the second call the function assumes those are not references but parameter descriptions and complains about missing fields.
for parameter in [p for p in parameters if isinstance(p, dict)]:
for parameter in [p for p in parameters if isinstance(p, dict) and '$ref' not in p]:
solves it. Maybe not the most elegant way.
@karec, any thoughts on this?
We might also have to update tests/docs about how to pass references because I think only the ref ID should be passed. Passing a complete ref won't trigger an exception but the reference is broken in the spec IIUC.
We can prevent
def path( self, path=None, operations=None, summary=None, description=None, parameters=None, **kwargs ): operations = deepcopy(operations) or OrderedDict() parameters = deepcopy(parameters) or 
Looks like a reasonable thing to do since those are mutated by helpers and cleanup functions.
Not sure this would solve the OP.
But this plus passing only ref name in YAML docstring should solve the OP AFAIU, so we also ought to fix test/docs to instruct users to only pass ref component name, not the whole
Sorry for delay, just seen the issue.
Like you said, checking if parameter is actually a
My bad on double call, didn't check for it
@lafrech quick up on this, but what do you think of allowing full
This would require more checks on
But shouldn't be a big deal and shouldn't break compatibility with current version
Thanks @karec for looking into this. No pb for the double call, I didn't see that coming either.
Passing the ref without the full path should be the recommended way as it lets apispec do the job of generating the path, and it makes the app more OAS version agnostic (this is not an objective that we absolutely want to reach, but I think it is nice). So I don't mind forbidding component paths in inputs as those are a bad habit anyway.
I don't mind the breaking change either as it is part of a major version. It's not to late to document it as part of 2.0.0.
I think I get your point. Visually it is nice to the user as it makes it clear he's passing a ref. But this is rather cosmetic. It needs a (very small) change on our side and a (slightly) extended API surface for a small benefit.
Everything that allows simplifying the code is welcome. I'd rather not try to support many ways to do the same thing and end up managing unforeseen cases. E.g. #441. I'm pretty sure this is a side-effect in
If the reference is a ref to a schema and has a schema name as ID, passing just the string is also consistent with how
Assuming we go on with #465 (documenting the breaking change), it's never to late to add another possibility if we discover some day that passing only the ref ID is blocking some use case, not just a cosmetic issue.
I use custom