Document Information

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

Servers and server variables

OpenAPI servers describe where your API is hosted (local, staging, production, etc.).

Kestrun supports both:

  • Static server URLs via Add-KrOpenApiServer -Url ...
  • Templated server URLs with variables like https://{env}.api.example.com

To define server variables, create one or more variables with New-KrOpenApiServerVariable and pass them to Add-KrOpenApiServer using -Variables.

$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'

In the generated document, these appear under servers[].variables.

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
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' `
    -Extensions ([ordered]@{
        'x-contact-department' = 'Developer Relations'
        'x-contact-hours' = '9am-5pm PST'
        'x-logo' = [ordered]@{
            'url' = 'https://www.kestrun.dev/assets/kestrun_abstract_transparent.png'
            'altText' = 'Kestrun logo'
        }
    })
Add-KrOpenApiLicense -Name 'Apache 2.0' -Identifier 'Apache-2.0'

# 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
        licenseName = $OpenInfo.info.license.name
        licenseIdentifier = $OpenInfo.info.license.identifier
        licenseUrl = $OpenInfo.info.license.url
    }
    Write-KrJsonResponse -InputObject $info -StatusCode 200
}

# Build and validate the OpenAPI specification
Build-KrOpenApiDocument
# Test and log OpenAPI document validation result
if (Test-KrOpenApiDocument) {
    Write-KrLog -Level Information -Message 'OpenAPI document built and validated successfully.'
} else {
    Write-KrLog -Level Error -Message 'OpenAPI document validation failed.'
}

# Start the server and keep logs open until exit
Start-KrServer -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 (optionally including -Extensions for x-* metadata).
  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. Contact supports vendor extensions via Add-KrOpenApiContact -Extensions (keys must start with x-). For licenses, you can use either -Url or the OpenAPI 3.1/3.2 -Identifier (SPDX).
  • 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