OpenAPI Best Practices

general > tag-description

Guidance

Tags alone are not very descriptive, so use descriptions to explain them.

For example, an 'Account' could be a user account, company information, bank account, or potential sales lead.

Message

Tags should have a description.

Examples

valid

openapi: "3.0.0"
tags:
  - name: example
    description: example API
info:
  title: example API
  version: "1.0.0"
paths: {}

invalid

openapi: "3.0.0"
tags:
  - name: example
info:
  title: example API
  version: "1.0.0"
paths: {}

Applies to WebAPI

Constraint

Type: Declarative Validation