Hello World

Create a simple OpenAPI 3.1 specification with a single greeting endpoint.

Full source

File: [pwsh/tutorial/examples/10.1-OpenAPI-Hello-World.ps1][10.1-OpenAPI-Hello-World.ps1]

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

# --- Logging / Server ---

New-KrLogger | Add-KrSinkConsole |
    Set-KrLoggerLevel -Value Debug |
    Register-KrLogger -Name 'console' -SetAsDefault

$srv = New-KrServer -Name 'OpenAPI Hello World' -PassThru

Add-KrEndpoint -Port $Port -IPAddress $IPAddress
# =========================================================
#                 TOP-LEVEL OPENAPI
# =========================================================

Add-KrOpenApiInfo -Title 'Hello World API' `
    -Version '1.0.0' `
    -Description 'A simple OpenAPI 3.1 example with a single endpoint.'

Add-KrOpenApiContact -Email 'support@example.com'
# Add Server info
Add-KrOpenApiServer -Url "http://$($IPAddress):$Port" -Description 'Local Server'

# =========================================================
#                 ROUTES / OPERATIONS
# =========================================================

Enable-KrConfiguration

Add-KrApiDocumentationRoute -DocumentType Swagger
Add-KrApiDocumentationRoute -DocumentType Redoc

# Simple GET endpoint with a text response

<#
.SYNOPSIS
    Get greeting message.
.DESCRIPTION
    Returns a simple greeting message.
#>
function getGreeting {
    [OpenApiPath(HttpVerb = 'get' , Pattern = '/greeting' )]
    param()
    Write-KrTextResponse -Text 'Hello, World!' -StatusCode 200
}

# =========================================================
#                OPENAPI DOC ROUTE / BUILD
# =========================================================

Add-KrOpenApiRoute  # Default pattern '/openapi/{version}/openapi.{format}'

# =========================================================
#                      RUN SERVER
# =========================================================

Start-KrServer -Server $srv -CloseLogsOnExit

Step-by-step

Logging: Register console logger as default.
Server: Create server named ‘OpenAPI Hello World’.
OpenAPI info: Add title, version, and description metadata.
OpenAPI contact: Set contact email for API support.
OpenAPI server: Add local server URL to specification.
Enable configuration and register API documentation routes.
Greeting endpoint: Add simple GET route returning plain text.
Build OpenAPI document and start server.

Try it

# Fetch the greeting
curl -i http://127.0.0.1:5000/greeting

# View the OpenAPI specification
curl http://127.0.0.1:5000/openapi/v1/openapi.json

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

Key Concepts

OpenAPI Info: Top-level metadata (title, version, description).
Servers: Define where the API is deployed (local, production, etc.).
Tags: Optional; used to group operations in documentation.
Endpoints: Each route is automatically registered as an OpenAPI operation.
Documentation Routes: Kestrun provides Swagger, ReDoc, Scalar, RapidOC, and Elements viewers.

Troubleshooting

Issue: OpenAPI document shows empty operations list.

Solution: Ensure Enable-KrConfiguration is called before Add-KrOpenApiRoute.

Issue: Swagger UI shows 404 error.

Solution: Verify Add-KrApiDocumentationRoute -DocumentType Swagger is called and the server is running.

Issue: OpenAPI JSON validation fails.

Solution: Run Test-KrOpenApiDocument to identify schema issues; ensure all required fields are provided.

References

Previous / Next

Previous: Introduction to OpenApi Next: Component Schemas