Add better property, & "alternate type", level deprecated support in documentation generation

[AMorgaut]

Content & configuration

Swagger/OpenAPI definition:

   /bar:
       put:
         deprecated: true
         parameters: 
         - name: baz
           deprecated: true
           in: query
           schema:
             type: string
         requestBody:
           content:
             application/json:
               schema:
                   type: object
                   properties:
                     a:
                       type: integer
                     b:
                       deprecated: true
                       type: integer
                     c:
                       oneOf:
                       - type: boolean
                       - type: integer
                         deprecated: true
             application/xml:
               schema:
                   type: object
                   properties:
                     a:
                       type: integer
                   xml:
                     name: _foo_

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 & 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 ;-)

[hkosova]

@AMorgaut with regard to this part:

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 ;-)

Feature requests to extend OpenAPI syntax should be submitted to the OpenAPI Specification repository:
https://github.com/OAI/OpenAPI-Specification/issues

Here's a couple of related syntax requests that you might be interested in:
Deprecating Security Schemes
Enhanced Operation Deprecation and versioning

Once the proposed syntax makes it into the Specification, tool developers can implement the new behavior.

[AMorgaut]

@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