OpenApi 中的摘要和描述有什么区别？答案

【问题标题】：What is the difference beween summary and description in OpenApi?OpenApi 中的摘要和描述有什么区别？
【发布时间】：2021-04-05 04:46:35
【问题描述】：

我注意到在OpenAPI Path Items 和其他一些构造中，您同时拥有summary 和description 字段，它们之间的区别是什么，它们各自的用途是什么？对我来说，他们似乎完成了同样的事情，我在文档中没有找到任何关于此的内容。起初这似乎是一个无意义的问题，但是由于您可以使用 OpenApi 生成 API 的代码，在文档等中使用它等等。我认为理清这些目的是有意义的。

【问题讨论】：

标签： swagger openapi

【解决方案1】：

`summary` 短，`description` 更详细。

将summary 视为对元素预期用途的简短一两句话解释。您将无法描述所有细微的细节，但在高层次上，它应该能够解释元素的用途。许多文档工具只会在有不同组件或端点列表时显示摘要，因此这是一个放置足够信息的好地方，让不熟悉的读者知道这是否会让他们做他们想做的事情.

另一方面，description 是完整的细节应该去的地方。例如，如果您有特殊的enum 值，则可以包含每个值的行为表。如果您有一个在 OpenAPI 中不容易定义的具有特殊行为的端点，您可以在这里向读者解释这些细节。

许多元素可能很简单，不需要很多细节，因此您可能会发现您的摘要就足够了。如果description 不存在（反之亦然），不同的文档工具可能会自动使用summary，但您需要验证您的特定工具是否执行此操作。我个人的偏好是默认使用description，并且仅在description 过于冗长时使用summary。

【讨论】：

summary 短，description 更详细。

`summary` 短，`description` 更详细。