From 25e85dc9ba2946d705b03fd94bbb510b56ab2cf2 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sat, 24 May 2025 17:05:14 +0100 Subject: [PATCH] Add a clear overview of summary vs description --- specification/docs.md | 7 +++++++ specification/index.md | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/specification/docs.md b/specification/docs.md index de298e4..bee863e 100644 --- a/specification/docs.md +++ b/specification/docs.md @@ -11,6 +11,13 @@ Besides machine-readable descriptions, an OpenAPI Description (OAD) can also inc This page shows how to take full advantage of special documentation capabilities in OpenAPI like markdown syntax or example objects. +## Summary vs Description + +Many objects support both `summary` and `description` fields, and this is especially useful where documentation or other tools might show items in either list or detail view. + + - `summary` is used for list view, and should be kept short. A single-sentence summary works well. + - `description` is shown when the item is being viewed in detail. The descriptions support markup and give you space to include as much information for your users as you want to. Don't be afraid to add paragraph breaks, links, or even bullet lists in these fields. + ## The Description Field Almost every object in the OpenAPI Specification accepts a `description` field which can provide additional information for developers, beyond what can be automatically generated from the API descriptions. diff --git a/specification/index.md b/specification/index.md index a0f3e63..b78a103 100644 --- a/specification/index.md +++ b/specification/index.md @@ -17,5 +17,5 @@ The following pages introduce the syntax and structure of an OpenAPI Description - [Content of Message Bodies](content): `content` and `schema`. - [Parameters and Payload of an Operation](parameters): `parameters` and `requestBody`. - [Reusing Descriptions](components): `components` and `$ref`. -- [Providing Documentation and Examples](docs): `description` and `example`/`examples`. +- [Providing Documentation and Examples](docs): `summary`, `description` and `example`/`examples`. - [API Servers](servers): `servers`.