I noticed that in OpenAPI Path Items and some other constructs you have both summary and description fields, what is the difference between those, and what is the purpose of each? For me, they seem to accomplish the same thing, and I did not find anything about this in the documentation. It might seem like a non-sense question at first, but since you can use OpenApi to generate API's code, use it in documentation etc. etc. I think it makes sense to clear up the purpose of these.
What is the difference beween summary and description in OpenApi?
Viewed 2811
1 Answers
summary is short, description is more detailed.
Think of the summary as a short one or two sentence explanation of what the intended purpose of the element is. You won't be able to describe all the subtle details, but at a high level, it should be able to explain the purpose of the element. Many documentation tools will only display the summary when there's a list of different components or endpoints, so this is a good place to put just enough information to let an unfamiliar reader know if this is the thing that will let them do what they want to do.
On the other hand, description is where the full details should go. For example, if you have special enum values, you can include a table of the behavior of each value. If you have an endpoint with special behavior not easily defined in OpenAPI, this is where you'd explain to the reader those details.
Many elements may be straightforward and not need a lot of details, so you may find your summary is sufficient. Different documentation tools may automatically use summary if description is not present (or vice versa), though you will want to verify that your particular tool does this. My personal preference is to default to description, and only use summary when the description is too verbose.
Related