Structural improvements: inheritance on paths and its sublevels #116
Replies: 8 comments
-
It definitely looks cleaner, however:
|
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
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 :-)
Here'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 |
Beta Was this translation helpful? Give feedback.
-
@arno-di-loreto Great proposal, it removes a lot of unnecessary duplication from Swagger files.
But it's very easy to solve if we support
So path-level P.S. @arno-di-loreto Such big code samples make Github issues harder to scroll. |
Beta Was this translation helpful? Give feedback.
-
Thanks @IvanGoncharov . I've replaced the full example by a link to a gist. |
Beta Was this translation helpful? Give feedback.
-
I'm moving this to Moonwalk as big structural changes cannot happen before then. |
Beta Was this translation helpful? Give feedback.
-
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:Beta Was this translation helpful? Give feedback.
All reactions