Skip to content

Improve docs about summary and description #2393

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

Closed
wants to merge 6 commits into from
Closed

Improve docs about summary and description #2393

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3f03dfc
Add summary/description definitions and reference links
InfoSec812 Nov 2, 2020
18151dd
Remove reference to 120 character limit
InfoSec812 Nov 2, 2020
d31ae90
Change wording from "fields" to "objects"
InfoSec812 Nov 2, 2020
1dad0d9
Added summary/description to TOC
InfoSec812 Nov 2, 2020
080aecf
Merge branch 'improve_docs_about_summary_and_description' of github.c…
InfoSec812 Nov 2, 2020
45a413f
Remove redundant explaination of rich text
InfoSec812 Nov 2, 2020
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
28 changes: 18 additions & 10 deletions versions/3.1.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp
- [Path Templating](#pathTemplating)
- [Media Types](#mediaTypes)
- [HTTP Status Codes](#httpCodes)
- [Summaries](#summary)
- [Descriptions](#description)
- [Specification](#specification)
- [Versions](#versions)
- [Format](#format)
Expand Down Expand Up @@ -96,6 +98,12 @@ Some examples of possible media type definitions:
The HTTP Status Codes are used to indicate the status of the executed operation.
The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

##### <a name="summary"></a>Summaries
In various places throughout the OpenAPI Specification, objects may have a `summary`. The summary is intended to be a short overview of that item.

##### <a name="description"></a>Descriptions
In various places throughout the OpenAPI Specification, objects may have a `description`. The description is intended to be a long-form explanation of that item and MAY be arbitrary length. It MAY contain [Rich Text](#richText) as explained below.

## Specification

### Versions
Expand Down Expand Up @@ -202,8 +210,8 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi
Field Name | Type | Description
---|:---:|---
<a name="infoTitle"></a>title | `string` | **REQUIRED**. The title of the API.
<a name="infoSummary"></a>summary | `string` | A short summary of the API.
<a name="infoDescription"></a>description | `string` | A short description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="infoSummary"></a>summary | `string` | A short [summary](#summary) of the API.
<a name="infoDescription"></a>description | `string` | A short [description](#description) of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
<a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
<a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
Expand Down Expand Up @@ -730,8 +738,8 @@ The path itself is still exposed to the documentation viewer but they will not k
Field Name | Type | Description
---|:---:|---
<a name="pathItemRef"></a>$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined.
<a name="pathItemSummary"></a>summary| `string` | An optional, string summary, intended to apply to all operations in this path.
<a name="pathItemDescription"></a>description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="pathItemSummary"></a>summary| `string` | An optional, string [summary](#summary), intended to apply to all operations in this path.
<a name="pathItemDescription"></a>description | `string` | An optional, string [description](#description), intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
<a name="pathItemPut"></a>put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
<a name="pathItemPost"></a>post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
Expand Down Expand Up @@ -839,8 +847,8 @@ Describes a single API operation on a path.
Field Name | Type | Description
---|:---:|---
<a name="operationTags"></a>tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
<a name="operationSummary"></a>summary | `string` | A short summary of what the operation does.
<a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="operationSummary"></a>summary | `string` | A short [summary](#summary) of what the operation does.
<a name="operationDescription"></a>description | `string` | A verbose [description](#description) of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
<a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
Expand Down Expand Up @@ -1936,8 +1944,8 @@ transactionCallback:
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="exampleSummary"></a>summary | `string` | Short description for the example.
<a name="exampleDescription"></a>description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="exampleSummary"></a>summary | `string` | Short [summary](#summary) for the example.
<a name="exampleDescription"></a>description | `string` | Long [description](#description) for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
<a name="exampleExternalValue"></a>externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive.

Expand Down Expand Up @@ -2241,8 +2249,8 @@ A simple object to allow referencing other components in the OpenAPI document, i
Field Name | Type | Description
---|:---:|---
<a name="referenceRef"></a>$ref | `string` | **REQUIRED**. The reference string.
<a name="referenceSummary"></a>summary | `string` | A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not define a `summary` field, then this field has no effect.
<a name="referenceDescription"></a>description | `string` | A description which by default SHOULD override that of the referenced component. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. If the referenced object-type does not define a `description` field, then this field has no effect.
<a name="referenceSummary"></a>summary | `string` | A short [summary](#summary) which by default SHOULD override that of the referenced component. If the referenced object-type does not define a `summary` field, then this field has no effect.
<a name="referenceDescription"></a>description | `string` | A [description](#description) which by default SHOULD override that of the referenced component. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. If the referenced object-type does not define a `description` field, then this field has no effect.

This object cannot be extended with additional properties and any properties added SHALL be ignored.

Expand Down