Giraffe.OpenApi 0.0.1

dotnet add package Giraffe.OpenApi --version 0.0.1                
NuGet\Install-Package Giraffe.OpenApi -Version 0.0.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Giraffe.OpenApi" Version="0.0.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Giraffe.OpenApi --version 0.0.1                
#r "nuget: Giraffe.OpenApi, 0.0.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Giraffe.OpenApi as a Cake Addin
#addin nuget:?package=Giraffe.OpenApi&version=0.0.1

// Install Giraffe.OpenApi as a Cake Tool
#tool nuget:?package=Giraffe.OpenApi&version=0.0.1                

Giraffe

Giraffe.OpenApi

An extension for the Giraffe Web Application framework with functionality to auto generate OpenApi documentation spec from code.

NuGet Info

Table of Contents

About

Giraffe.OpenApi is a library that extends the Giraffe Web Application framework with functionality to auto generate OpenApi documentation spec from code. This means that you can define your API endpoints using Giraffe and generate OpenApi or Swagger documentation from it.

Inspired by the Oxpecker.OpenApi library, but adapted to work with Giraffe.

Getting Started

Add the Giraffe.OpenApi NuGet package to your project:

dotnet add package Giraffe.OpenApi

Two use cases:

open Giraffe
open Giraffe.EndpointRouting
open Giraffe.OpenApi

let endpoints = [
    // addOpenApi supports passing detailed configuration
    POST [
        route "/product" (text "Product posted!")
            |> addOpenApi (OpenApiConfig(
                requestBody = RequestBody(typeof<Product>),
                responseBodies = [| ResponseBody(typeof<string>) |],
                configureOperation = (fun o -> o.OperationId <- "PostProduct"; o)
            ))
    ]
    // addOpenApiSimple is a shortcut for simple cases
    GET [
        routef "/product/{%i}" (
            fun id ->
                forecases
                |> Array.find (fun f -> f.Id = num)
                |> json
        )
            |> configureEndpoint _.WithName("GetProduct")
            |> addOpenApiSimple<int, Product>
    ]
]

Documentation

Integration

Since Giraffe.OpenApi works on top of Microsoft.AspNetCore.OpenApi and Swashbuckle.AspNetCore packages, you need to do standard steps:

let configureApp (appBuilder: IApplicationBuilder) =
    appBuilder
        .UseRouting()
        .UseSwagger() // For generating OpenApi spec
        .UseSwaggerUI() // For viewing Swagger UI
        .UseGiraffe(endpoints)
        .UseGiraffe(notFoundHandler)

let configureServices (services: IServiceCollection) =
    services
        .AddRouting()
        .AddGiraffe()
        .AddEndpointsApiExplorer() // Use the API Explorer to discover and describe endpoints
        .AddSwaggerGen() // Swagger dependencies
    |> ignore

To make endpoints discoverable by Swagger, you need to call one of the following functions: addOpenApi or addOpenApiSimple on the endpoint.

NOTE: you don't have to describe routing parameters when using those functions, they will be inferred from the route template automatically.

addOpenApi

This method is used to add OpenApi metadata to the endpoint. It accepts OpenApiConfig object with the following optional parameters:

type OpenApiConfig (?requestBody : RequestBody,
                    ?responseBodies : ResponseBody seq,
                    ?configureOperation : OpenApiOperation -> OpenApiOperation) =
    // ...

Response body schema will be inferred from the types passed to requestBody and responseBodies parameters. Each ResponseBody object in sequence must have different status code.

configureOperation parameter is a function that allows you to do very low-level modifications the OpenApiOperation object.

addOpenApiSimple

This method is a shortcut for simple cases. It accepts two generic type parameters - request and response, so the schema can be inferred from them.

let addOpenApiSimple<'Req, 'Res> = ...

If your handler doesn't accept any input, you can pass unit as a request type (works for response as well).

configureEndpoint

The two methods above return Endpoint object, which can be further configured using configureEndpoint method provided by Giraffe. It accepts Endpoint object and returns the same object, so you can chain multiple calls.

let endpoints = [
    GET [
        route "/hello" (text "Hello, World!")
        |> configureEndpoint _.WithName("HelloWorld")
        |> configureEndpoint _.WithDescription("Simple hello world endpoint")
        |> configureEndpoint _.WithSummary("Hello world")
        |> addOpenApiSimple<unit, string>
    ]
]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.0.1 689 8/8/2024

Initial Version