Closed arno-di-loreto closed 3 months ago
parent OAI/OpenAPI-Specification#560
It definitely looks cleaner, however:
tags
belong under the Info Object and not the Paths Object. They are not a global definition of tags that are applied to all paths but a documentation of what the tags mean.parameters
, /path
, security
, /path2
and that's just difficult to read. I get what you're trying to do with the other tickets and inheritance/overriding of the globals, but I don't think that's enough to justify it. As an alternative, we can either collect all the globals under a key (globals
?) at the same level as paths
, info
and so on, or we can move the entire set of globals and paths under a common node (root
?), having the globals defined alongside the paths
key, keeping a similar structure to what it is now, just pushing it down a node.parameters
). globals
idea on each level to group "shared things" and make the spec more easy to read). In the end it would be just like parameters
on path level in the existing version but extended to all shared things (definitely need a better name):paths:
globals (or shared or another word):
# Tags, parameters, responses, responses headers, security
# (which were on root on Tony's proposal) and new others applying
# to all paths
# Everything can be overridden by sub levels.
{/paths}:
globals (or shared or another word):
# Tags, parameters, responses, responses headers,
# security and new other things applying to all operations
# Everything can be overridden by sub levels.
{operation like get/post/...}:
responses:
globals (or shared or another word):
# Responses headers and new other things applying to all responses
# Everything can be overridden by sub levels.
{http status | default):
# response object
security
is overridden, parameters
is added, for example.First things first: thank you and all the team for reading my issues and giving feedback, there are so many issues and comments in this repo! It took me a long time to figure which of my ideas were already there ... and I missed some of them :-)
produces
could also be inherited to the response levelsecurity
and parameters
inheritance behaviour, but that's already the case in version 2 :-)parameters
principle to everything.
shared
on each levelallDefinition
, not fond of the name and I'm wondering if it's useful to do thatHere's the full 3.0 example based on the last file of part 6 of my tutorial:
https://gist.github.com/arno-di-loreto/707f15ff819428bdbd7a3acab3bc8333
@arno-di-loreto Great proposal, it removes a lot of unnecessary duplication from Swagger files. But I totally agree with @webron on:
Another issue with both globals and consistency is that they are already inconsistent. security is overridden, parameters are added, for example.
But it's very easy to solve if we support default
property along side with shared
.
And it will be very simple algorithm for figuring out values for particular operation:
default
set as property values but only if matching property is undefined at the moment.shared
prepend to the current value of the property.So path-level parameters
from 2.0 will move to path-level shared
.
And root-level security
will move to paths
-level default
.
It will also allow for many other things that not possible in 2.0.
For example, to define global OAuth scopes but allow individual operations to add their own.
P.S. @arno-di-loreto Such big code samples make Github issues harder to scroll. Can you please replace sample from your last comment with a link to a Gist?
Thanks @IvanGoncharov . I've replaced the full example by a link to a gist.
I'm moving this to Moonwalk as big structural changes cannot happen before then.
Based on @fehguy structure modification proposition on OAI/OpenAPI-Specification#563 and my ideas gathered while writing OpenAPI spec and writing my OpenAPI spec tutorial, I propose a new structure for the document.
Tony's proposal (focus on paths and what it needs):
On root we only keep:
paths
: The API's description (improved paths, see below)schemas
: All reusable objects used to describe to APIOn
paths
, the idea is to extend what we already have withparameters
declaration on path and operation level to everything that can be declared for an operation (parameters, responses, headers, ...) on all levels:What we have now:
Extending this principle to all levels and properties in
paths
and its sub-level: