8 months ago

OpenAPI Tags are a great way to organize the API endpoints in https://bump.sh/blog/api-contracts-extended-introduction. When developing APIs, it's essential to document the API so that other developers, whether internal or external, can use the API effectively.

tags: - name: Diffs description: Diff summary of changes in the API - name: Ping description: Monitoring status endpoints - name: Previews description: Preview for documentation file - name: Versions description: Deploy your API contracts - name: Validations description: Check & validate your API contracts - name: Hubs description: Interact with your Hubs

Instead, make sure you define and describe every tag only once in the root Tag Object, like in the snippet below: tags: - name: Diffs description: Diff summary of changes in the API - name: Versions description: Deploy your API contracts - name: Validations description: Check & validate your API contracts - name: Hubs description: Interact with your Hubs - name: "Documentation change" description: Check & validate your API contracts

On the other hand, notice how every endpoint in the API contract below has a tag also defined in the root Tag Object: tags: - name: Diffs description: Diff summary of changes in the API - name: Ping description: Check the API status - name: Previews description: Preview changes to an API Documentation - name: Versions description: Deploy your API contracts - name: Validations description: Check & validate your API contracts - name: Hubs description: Interact with your Hubs paths: /diffs: post: tags: [ Diffs ] /diffs/{id}: get: tags: [ Diffs ] /hubs/{hub_id_or_slug}: get: tags: [ Hubs ] /versions: post: tags: [ Versions ] /validations: post: tags: [ Validations ] /previews: post: tags: [ Previews ] /previews/{preview_id}: put: tags: [ Previews ] /versions/{version_id}: get: tags: [ Versions ] /ping: get: tags: [ Ping ]