Skip to content

added deprecated fields #637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 14, 2016
Merged

added deprecated fields #637

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -586,6 +586,7 @@ Field Name | Type | Description
<a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "body".
<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
<a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.

If [`in`](#parameterIn) is `"body"`:

Expand Down Expand Up @@ -1242,6 +1243,7 @@ Field Name | Type | Description
<a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
<a name="schemaExample"></a>example | Any | A free-form property to include a an example of an instance for this schema.
<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and should be transitioned out of usage.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned by @IvanGoncharov, this needs more clarification.
You don't actually deprecate a schema, you deprecate a property in a object model (or you deprecate a parameter, or a whole path/operation, but this is a different issue).
The problem (inherited from JSON Schema) is that an object's property consists of just a name and a schema of its value, and thus we can only add stuff to the value schema, as done here.
Maybe add something similar to the "schemaXml" cited above:

This MAY be used only on properties schemas. It has no effect on root schemas. If used with a value of
true, it specifies that this property is deprecated and should be transitioned out of usage.

An alternative would be to do this similar to required and add a property to the containing schema, with a list of deprecated properties.

In addition, when something is deprecated I often feel the need to mention why it is deprecated, and what to use instead. Of course this can be put into the description, but maybe it is better to make this a string property, with the value being the deprecation documentation? (When using the alternative mentioned above, it could be made an object mapping property name → deprecation info, instead of an array of property names.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but maybe it is better to make this a string property, with the value being the deprecation documentation?

@ePaul It was discussed here: #540
And it's a slippery slope since next thing people will ask to implement is the date of deprecation.
IMHO it's very simple rule of thumb if you can programmatically act based on field value; but if it's a text for a user to read then why not use description for that.

One thing that could be added to Swagger spec is a recommendation to add full content of description field into the text of deprecation warning.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the link. You are right, I guess putting it in the description is enough. (And the recommendation to do so should be here.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think such recommendations should be covered outside the spec and within some best practice docs - #589.


##### Patterned Objects

Expand Down