OpenApi 中的摘要和描述有什么区别？
What is the difference beween summary and description in OpenApi?
我注意到在 OpenAPI Path Items 和其他一些结构中，您同时拥有 summary 和 description 字段，它们之间有什么区别，它们的用途是什么？对我来说，他们似乎完成了同样的事情，我在文档中没有找到任何相关信息。起初这似乎是一个无意义的问题，但由于您可以使用 OpenApi 生成 API 的代码，在文档等中使用它。我认为弄清楚这些的目的是有意义的。
summary简短，description更详细。
将 summary 视为对元素预期用途的简短的一两句话解释。您将无法描述所有细微的细节，但在高层次上，它应该能够解释元素的用途。许多文档工具只会在有不同组件或端点的列表时显示摘要，因此这是放置足够信息的好地方，让不熟悉的人 reader 知道这是否会让他们做什么他们想做。
另一方面，description 是完整的详细信息所在的位置。例如，如果您有特殊的 enum 值，则可以包含每个值的行为的 table。如果您有一个具有特殊行为的端点，在 OpenAPI 中不容易定义，您可以在这里向 reader 解释这些细节。
许多元素可能很简单，不需要太多细节，因此您可能会发现您的总结就足够了。如果 description 不存在（反之亦然），不同的文档工具可能会自动使用 summary，但您需要验证您的特定工具是否这样做。我个人的偏好是默认为 description，并且仅在 description 过于冗长时才使用 summary。
我注意到在 OpenAPI Path Items 和其他一些结构中，您同时拥有 summary 和 description 字段，它们之间有什么区别，它们的用途是什么？对我来说，他们似乎完成了同样的事情，我在文档中没有找到任何相关信息。起初这似乎是一个无意义的问题，但由于您可以使用 OpenApi 生成 API 的代码，在文档等中使用它。我认为弄清楚这些的目的是有意义的。
summary简短，description更详细。
将 summary 视为对元素预期用途的简短的一两句话解释。您将无法描述所有细微的细节，但在高层次上，它应该能够解释元素的用途。许多文档工具只会在有不同组件或端点的列表时显示摘要，因此这是放置足够信息的好地方，让不熟悉的人 reader 知道这是否会让他们做什么他们想做。
另一方面，description 是完整的详细信息所在的位置。例如，如果您有特殊的 enum 值，则可以包含每个值的行为的 table。如果您有一个具有特殊行为的端点，在 OpenAPI 中不容易定义，您可以在这里向 reader 解释这些细节。
许多元素可能很简单，不需要太多细节，因此您可能会发现您的总结就足够了。如果 description 不存在（反之亦然），不同的文档工具可能会自动使用 summary，但您需要验证您的特定工具是否这样做。我个人的偏好是默认为 description，并且仅在 description 过于冗长时才使用 summary。