Tags and External Docs

Group operations with tags and attach external documentation links to both the document and specific routes.

Full source

File: [pwsh/tutorial/examples/10.7-OpenAPI-Tags.ps1][10.7-OpenAPI-Tags.ps1]

<#
    Sample: OpenAPI Tags and External Documentation
    Purpose: Demonstrate organizing operations with tags and linking external documentation to tags.
    File:    10.7-OpenAPI-Tags.ps1
    Notes:   Shows tag-based operation organization, multi-tag assignment, and external documentation association.
#>

param(
    [int]$Port = 5000,
    [IPAddress]$IPAddress = [IPAddress]::Loopback
)

# Configure logging
New-KrLogger |
    Add-KrSinkConsole |
    Set-KrLoggerLevel -Value Information |
    Register-KrLogger -Name 'console' -SetAsDefault | Out-Null

# Create server instance
$srv = New-KrServer -Name 'OpenAPI Tags Demo'

# Configure endpoint
Add-KrEndpoint -Port $Port -IPAddress $IPAddress

# Set document-level metadata
Add-KrOpenApiInfo -Title 'Tags Demo API' -Version '1.0.0' -Description 'Demonstrates operation tags with external documentation links.'

# Define tags with descriptions and optional external documentation links
Add-KrOpenApiTag -Name 'orders' -Description 'Operations for listing orders' -ExternalDocs (New-KrOpenApiExternalDoc -Description 'Order docs' -Url 'https://example.com/orders')
Add-KrOpenApiTag -Name 'health' -Description 'Service health endpoints'
Add-KrOpenApiTag -Name 'operations' -Description 'Common operational endpoints'

# Add top-level external documentation link
Add-KrOpenApiExternalDoc -Description 'API handbook' -Url 'https://example.com/api-handbook'

# Apply configuration and register documentation routes
Enable-KrConfiguration
Add-KrApiDocumentationRoute -DocumentType Swagger
Add-KrApiDocumentationRoute -DocumentType Redoc
Add-KrOpenApiRoute

# Route function demonstrating multiple tag assignment and tag-based organization
function getOrders {
    [OpenApiPath(HttpVerb = 'get', Pattern = '/orders', Summary = 'List demo orders', Description = 'Returns a simple list of order identifiers.', Tags = ('orders', 'operations'))]
    [OpenApiResponse(StatusCode = '200', Description = 'List of orders', ContentType = 'application/json')]
    param()
    Write-KrJsonResponse -InputObject @{ orders = @('order-1001', 'order-2002') }
}

# Route function demonstrating multiple tag assignment
function getHealth {
    [OpenApiPath(HttpVerb = 'get', Pattern = '/health', Summary = 'Service health', Description = 'Returns a simple health status payload.', Tags = ('health', 'operations'))]
    [OpenApiResponse(StatusCode = '200', Description = 'Health status', ContentType = 'application/json')]
    param()
    Write-KrJsonResponse -InputObject @{ status = 'healthy' }
}

# Build and validate the OpenAPI specification
Build-KrOpenApiDocument
Test-KrOpenApiDocument

# Start the server and keep logs open until exit
Start-KrServer -Server $srv -CloseLogsOnExit
Start-KrServer -Server $srv -CloseLogsOnExit

Step-by-step

  1. Register console logger and create the server.
  2. Add OpenAPI info and define document-level external docs.
  3. Declare tags (orders, health, operations) and attach external docs to the orders tag.
  4. Enable configuration and register Swagger/ReDoc plus the OpenAPI route.
  5. Define /orders and /health functions decorated with OpenApiPath (multiple tags) and response metadata.
  6. Build and test the OpenAPI document, then start the server.

Try it 

# View the spec with tag metadata
curl http://127.0.0.1:5000/openapi/v1/openapi.json | jq .tags

# Hit tagged endpoints
curl http://127.0.0.1:5000/orders
curl http://127.0.0.1:5000/health

# Browse Swagger UI
# Visit http://127.0.0.1:5000/swagger in your browser

Key Concepts

  • Tags: Group related operations for clearer docs navigation; operations can have multiple tags.
  • External docs: Attach URLs at document level and via tag metadata.
  • Route metadata: Use OpenApiPath (with multiple tags) and OpenApiResponse attributes to describe operations.
  • Doc viewers: Swagger/ReDoc routes render tags and external docs automatically.

Troubleshooting

Issue: Tags not appearing on operations.

  • Solution: Ensure each function includes Tags = @('tag1','tag2') on [OpenApiPath].

Issue: External docs link missing.

  • Solution: Provide a valid -Url on Add-KrOpenApiExternalDoc or pass -ExternalDocs to Add-KrOpenApiTag and rebuild the document.

Issue: Swagger or ReDoc 404s.

  • Solution: Confirm both Add-KrApiDocumentationRoute and Add-KrOpenApiRoute are called after Enable-KrConfiguration.

References

Previous / Next

Previous: Complete Components Next: Document Information