Add Builder to simplify openapi document object construction

A regular C# builder pattern would help a lot in many scenarios.
Building an object now is very complex...

Builder pattern is also the "de facto" in Aspnetcore.. so would make sense to expose a similar api

var openApiDocumentBuilder = new OpenApiDocumentBuilder()
     .WithServers(...)
     .WithOperation(...)
     .WithOperation(...)
     .WithSchema(...);
//... etc


var openApiDocument = openApiDocumentBuilder.Build();

Agreed, building it is clunky. Would you mind starting a discussion thread on ways that we could improve construction?

I very nice project i saw in the F# space is this one (it uses F# Computation Expressions CEs for the builder pattern), but probably with extension methods something much similar can be obtained.. (or maybe also the F# part could be included in the "official one" for the F# api)

https://github.com/akhansari/FSharp.OpenApi

let document =
    apiDocument {
        info (apiInfo {
            version "1.0.0"
            title "Swagger Petstore (Simple)"
        })
        servers [
            apiServer {
                url "http://petstore.swagger.io/api"
            }
        ]
        paths [
            "/pets", apiPathItem {
                operations [
                    OperationType.Get, apiOperation {
                        description "Returns all pets from the system that the user has access to"
                        responses [
                            HttpStatusCode.OK, apiResponse {
                                description "OK"
                            }
                        ]
                    }
                ]
            }
        ]
    }

let outputString =
    document.Serialize (OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json)

i guess the C# counterpart would be like

var document = 
    OpenApi.Builder()
          .WithInfo(....)
          .WithServers(...)
          .WithPaths(...)
          .Build();
          
  var openApiJsonV3String = document.Serialize (OpenApiSpecVersion.OpenApi3_0, OpenApiFormat.Json);

I came across this issue while drafting a proposal for a new API in ASP.NET Core that builds on top of Microsoft.OpenAPI (see dotnet/aspnetcore#44192).

IMO, it would be really neat to have a builder-style pattern for an OpenAPI document.

If someone wants to prototype a builder object, they are welcome to create a PR.

Navigation Menu

Repository navigation

Add Builder to simplify openapi document object construction #673

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add Builder to simplify openapi document object construction #673

Description

Activity

darrelmiller commented on Jan 23, 2022

jkone27 commented on Jan 24, 2022

captainsafia commented on Sep 26, 2022

darrelmiller commented on Apr 29, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions