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

Question

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

Answer 1

summary 简短，description 更详细。

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

另一方面，description 是完整的详细信息。例如，如果您有特殊的 enum 值，您可以包括每个值的行为表。如果您的端点具有在 OpenAPI 中不易定义的特殊行为，您可以在此处向读者解释这些详细信息。

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