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

Question

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

Answer 1

summary篇幅短，description内容更详细。

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

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

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