You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
While efficientely clear at the path method & query parameter levels, the deprecation status is not clear enough at the property level & for property alternative types
We currently have different/inconsistent representations of the deprecated status depending or where it applies
Level
Strike
Grey
Warning
Red deprecated
deprecated: true
drop in example
method
✔️
✔️
✔️
❌
❌
NA
parameter
❌
✔️
❌
✔️
❌
NA
property
❌
✔️
❌
❌
✔️
✔️
oneOf type
❌
✔️
❌
❌
✔️
❌
ref
❌
❌
❌
❌
✔️
❌
Describe the solution you'd like
Wherever a depracated flag is set, I'd expect a uniform combo of:
grey/italic fonct style & color
a red warning message
Additional context
Moreover
The deprecated flag is not accepted at (by schema) at those levels:
media type to deprecate a media type alternative (either in requestBody or responses)
paths property (ex /foo) to deprecate an URI whatever the method (currently requires one deprecated per method)
root or info, to deprecate a whole API definition (would currently require a deprecated for each method of each path)
servers item, to deprecate a server configuration compared to the others
but this should be a separated feature request ;-)
The text was updated successfully, but these errors were encountered:
@hkosova thanks for the references for the syntax part
Might be nice if once validated it could follow a consistent "deprecated" style in swagger UI
As you must have seen, I tried to provide a table to visualize how the style differs depending of the current deprecation context.
There might always be some specificities in some context, but usually, not that much ;-)
Anyway, not always simple to get the full overview of all possible use-cases
Content & configuration
Swagger/OpenAPI definition:
Is your feature request related to a problem?
While efficientely clear at the path method & query parameter levels, the deprecation status is not clear enough at the
property
level & forproperty alternative types
We currently have different/inconsistent representations of the deprecated status depending or where it applies
Describe the solution you'd like
Wherever a
depracated
flag is set, I'd expect a uniform combo of:Additional context
Moreover
The deprecated flag is not accepted at (by schema) at those levels:
paths
property (ex/foo
) to deprecate an URI whatever the method (currently requires onedeprecated
per method)root
orinfo
, to deprecate a whole API definition (would currently require adeprecated
for each method of each path)servers
item, to deprecate a server configuration compared to the othersThe text was updated successfully, but these errors were encountered: