added description field

[fehguy]

Fixes #534

[IvanGoncharov]

@fehguy Can you also add summary field. This will allow to create side-menus, you can't use description for that purpose since it can be huge and also contained markdown.
It also common problem see:
https://help.apiary.io/api_101/swagger-extensions/

[jharmn]

No harm done.

[fehguy]

@OAI/tdc please chime in with any objections to this

[erikvanzijst]

👍

[jharmn]

👍 (but I really want a here @fehguy )

[fehguy]

<= rats with fur

[ePaul]

Just to make sure: Is this meant to be a description for the path (i.e. the resource or group of resources), or a default description for each operation on this path, which can be overridden on operation level?

Either way it might need a clearer description.

[darrelmiller]

@ePaul My understanding is that it is the description of the set of resources pointed to by the path template.

[webron]

I'll be the bad guy here (sorry @erikvanzijst) and am going to vote 👎.

My reasoning being:

1. This does not really solve the issue brought up in the original issue. It's a workaround to tags having no hierarchy - I'd much rather deal with that then go with this. FWIW, this came up in 2.0 and we decided to keep it simple then.
2. This makes paths seem to be treated as organizational units, possibly resources. It is not the case. Many would consider /pets and /pets/{petId} to be a single resource, but being separate paths they will not be that in this case.
3. This will add to the confusion of organization level. Theoretically it can be seemed as multiple ways to a single approach, but I believe this will cause more issues than help.
4. Once we deal with 'what defines a unique path' in the next version, this will become even more meaningless, especially if we decide to include query parameters as uniqueness identifiers. Just think about it.

Please note I'm keeping the tooling out of the equation in this case.

[fehguy]

@OAI/tdc Please approve or reject.

[whitlockjc]

Could you squash your commits upon merge? Other than that, LGTM.

[darrelmiller]

After much internal debate I have decided to go 👍 on this. I believe it is fairly natural to some kind of describable semantic meaning to the resources identified by a path template. If we end up adding query parameters into the "path" then I think it will fit even better.

I don't like the confusion it adds by have two places to add descriptions, but the current location of description encourages "Retrieve the thing", "Update the thing", "Create the thing", "Delete the thing" style of docs. I'd prefer people spend more time telling me what then thing is and less telling my what the HTTP methods do.

I recognize that tags provide a workaround, but that workaround cause the description and the path to be in two different parts of the document and it requires generating tags for paths.

[netmilk]

@fehguy thanks for adding summary to this PR. I'd be super excited to see this in the future OAS.

Apiary is using the summary for generating the Table Of Contents in the documentation in two cases:

• there are no tags given at all
• multiple tags are used in any of the Path Item objects and the TOC is confusing.

In case there are no summaries or tags given in the document, Apiary is just rendering URIs in the TOC.

We have users reaching out our support and asking how to override the URIs in the TOC and adding summary to the Path Item object is solving their problem.

So sending a big 👍 from Apiary.

[earth2marsh]

I'll add a 👍 to the description to paths. I'm somewhat conflicted around summary, since in my mind that means an abbreviated description when I suspect it is being used as a name or title. But I wouldn't hold up the description improvement for that.

[tedepstein]

@OAI/tdc, glad to see that this is being included. I can understand why it was controversial, but I strongly support @darrelmiller's analysis that "...it is fairly natural to [add] some kind of describable semantic meaning to the resources identified by a path template."

But that isn't really consistent with the language in the spec, which says this is a "description, intended to apply to all operations in this path."

If it describes the operations (and I hope that's not the case), then I agree with @ePaul: it's important to specify whether operation-level descriptions override or supplement path-level descriptions. It's also rather unlikely that you'd want a single summary to apply to all operations defined within a given path.

If it describes the pathItem itself, independent of its operations, then the specification language should communicate that meaning.

Personally, I don't think OpenAPI should shy away from acknowledging pathItem as an important organizational component of an API description. Syntactically, it's very substantial. It contains parameters and operations. It feels odd and counter-intuitive to organize the hierarchy this way without giving first-class status to the pathItem.

Tags are a very flexible way of grouping operations, even more flexible if they eventually allow a hierarchy. But in many cases, path-level organization is sufficient and is most natural to the API. If anything, it might be helpful to introduce (in a later revision!!!) a grouping construct for pathItems, to address @webron's case of /pets and /pets/{petId} forming a single "resource" in the mind of the API designer.

Fully recognizing that it's harder for tools and documentation formats to cope with a range of possible ways in which an API's documentation might be organized. The API author might have used any combination of path-level, operation-level, tag-level and (maybe, someday) path-group-level documentation. I think the answer is for documentation tools to be more adaptable and configurable, so they can present the API in the organizational structure the designer had in mind.

IMO, this is just part of OpenAPI's path from an opinionated, prescriptive subset of the web API space to a more general standard, suitable for a broader range of uses. If you made it this far, thanks for reading! ;-)