Add Builder to simplify openapi document object construction

[jkone27]

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();
     

[darrelmiller]

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

[jkone27]

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);
          

[captainsafia]

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.

[darrelmiller]

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