Document Information

Populate OpenAPI document metadata including title, version, summary, terms of service, contact, license, and server list.

Full source

File: [pwsh/tutorial/examples/10.8-OpenAPI-Document-Info.ps1][10.8-OpenAPI-Document-Info.ps1]

<#
    Sample: OpenAPI Document Information
    Purpose: Demonstrate how to populate document-level metadata including title, version, contact, license, and servers.
    File:    10.8-OpenAPI-Document-Info.ps1
    Notes:   Shows document info setup, server configuration with environment variables, and metadata retrieval via endpoint.
#>

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 Document Info Demo'

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

# Set document-level metadata: title, version, description, summary, and terms
Add-KrOpenApiInfo -Title 'Document Info API' -Version '1.0.0' -Description 'Shows how to populate document metadata.' -Summary 'Document metadata demo' -TermsOfService 'https://example.com/terms'

# Add contact and license information
Add-KrOpenApiContact -Name 'API Support' -Email 'support@example.com' -Url 'https://example.com/support'
Add-KrOpenApiLicense -Name 'MIT' -Url 'https://opensource.org/licenses/MIT' -Identifier 'MIT'

# Configure server endpoints with optional environment variable substitution
$serverVars = New-KrOpenApiServerVariable -Name 'env' -Default 'dev' -Enum @('dev', 'staging', 'prod') -Description 'Deployment environment'
Add-KrOpenApiServer -Url 'https://{env}.api.example.com' -Description 'Environment-specific endpoint' -Variables $serverVars
Add-KrOpenApiServer -Url 'https://api.example.com' -Description 'Production'
Add-KrOpenApiServer -Url 'https://staging-api.example.com' -Description 'Staging'
Add-KrOpenApiServer -Url '/' -Description 'Self'

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

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

<#
.SYNOPSIS
    Get API document info.
.DESCRIPTION
    Returns OpenAPI document metadata as a JSON payload, demonstrating
    access to the configured document information.
#>
function getApiInfo {
    [OpenApiPath(HttpVerb = 'get', Pattern = '/info')]
    [OpenApiResponse(Description = 'Returns document metadata sample', ContentType = 'application/json')]
    param()

    # Retrieve the built OpenAPI document and extract metadata
    $OpenInfo = Get-KrOpenApiDocument
    $info = [ordered]@{
        title = $OpenInfo.info.title
        description = $OpenInfo.info.description
        version = $OpenInfo.info.version
        termsOfService = $OpenInfo.info.termsOfService
        contact = $OpenInfo.info.contact.email
        license = $OpenInfo.info.license.name
    }
    Write-KrJsonResponse -InputObject $info -StatusCode 200
}

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

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

Step-by-step

  1. Configure console logger and create server instance with New-KrServer.
  2. Configure endpoint with Add-KrEndpoint specifying port and IP address.
  3. Set document metadata with Add-KrOpenApiInfo (title, version, description, summary, terms).
  4. Add contact and license information via Add-KrOpenApiContact and Add-KrOpenApiLicense.
  5. Define server endpoints using Add-KrOpenApiServer, including templated environment variables via New-KrOpenApiServerVariable.
  6. Add top-level external documentation link with Add-KrOpenApiExternalDoc.
  7. Enable configuration and register documentation routes (Swagger, ReDoc, OpenAPI endpoint).
  8. Create a route function getApiInfo that retrieves and returns document metadata using Get-KrOpenApiDocument.
  9. Build and validate the OpenAPI document with Build-KrOpenApiDocument and Test-KrOpenApiDocument.
  10. Start the server with Start-KrServer.

Try it 

# Fetch the document metadata route
curl http://127.0.0.1:5001/info

# Inspect servers/contact/license in the spec
curl http://127.0.0.1:5001/openapi/v1/openapi.json | jq '{info, servers}

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

Key Concepts

  • Document Info: Title, version, description, summary, and terms of service for the API.
  • Contact & License: Standard OpenAPI metadata for ownership and usage terms.
  • Servers: Multiple deployment endpoints plus templated server variables.
  • External Docs: Optional top-level links to guides or handbooks.

Troubleshooting

Issue: Contact or license missing in the rendered spec.

  • Solution: Confirm Add-KrOpenApiContact and Add-KrOpenApiLicense are called before Build-KrOpenApiDocument.

Issue: Servers not showing up.

  • Solution: Ensure Add-KrOpenApiServer is invoked for each endpoint and that server variables have defaults.

Issue: Swagger UI returns 404.

  • Solution: Verify Enable-KrConfiguration, Add-KrApiDocumentationRoute, and Add-KrOpenApiRoute run before starting the server.

References

Previous / Next

Previous: Tags and External Docs Next: Component Headers