BREAKING: create generic engine.OutputOpenAPISpec for use in all engines

[dylanhitt]

This pulls out as much functionality as possible in regards to generating the assets when calling engine.OutputOpenApiSpec.

This change is breaking in so far as the OpenAPIConfig will be composed of EngineOpenAPIConfig. I personally don't like these names but I want to ask about changing it here first. I would prefer that we change OpenAPIConfig to ServerOpenAPIConfig and EngineOpenAPIConfig becomes the OpenAPIConfig. The current OpenAPIConfig does have some uniqueness in regards to the fuego.Server. We probably could consolidate nearly all of it though if in #260 we created an interface that dealt with route/url registration, but I'm not sure how far we want to take this. Or if someone can think of a better name for EngineOpenAPIConfig.

For instance every framework we bring in would need to be able to handle something like this to make it work

// OutputOpenAPISpec takes the OpenAPI spec and outputs it to a JSON file and/or serves it on a URL.
// Also serves a Swagger UI.
// To modify its behavior, use the [WithOpenAPIConfig] option.
func (s *Server) OutputOpenAPISpec() openapi3.T {
	s.OpenAPI.Description().Servers = append(s.OpenAPI.Description().Servers, &openapi3.Server{
		URL:         s.url(),
		Description: "local server",
	})

	if !s.OpenAPIConfig.DisableSwagger {
		s.registerOpenAPIRoutes(s.Engine.OutputOpenApiSpec())
	}

	return *s.OpenAPI.Description()
}

// Registers the routes to serve the OpenAPI spec and Swagger UI.
func (s *Server) registerOpenAPIRoutes(jsonSpec []byte) {
	GetStd(s, s.OpenAPIConfig.JsonUrl, func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		_, _ = w.Write(jsonSpec)
	})
	s.printOpenAPIMessage(fmt.Sprintf("JSON spec: %s%s", s.url(), s.OpenAPIConfig.JsonUrl))

	if !s.OpenAPIConfig.DisableSwaggerUI {
		Register(s, Route[any, any]{
			BaseRoute: BaseRoute{
				Method: http.MethodGet,
				Path:   s.OpenAPIConfig.SwaggerUrl + "/",
			},
		}, s.OpenAPIConfig.UIHandler(s.OpenAPIConfig.JsonUrl))
		s.printOpenAPIMessage(fmt.Sprintf("OpenAPI UI: %s%s/index.html", s.url(), s.OpenAPIConfig.SwaggerUrl))
	}
}

[dylanhitt]

Assuming this is acceptable. I believe really the decisions regarding how far we take this will be based on how far we want to take #260.

[EwenQuim]

Nice PR! We just need to de-embed the OpenAPIServerConfig field.

[ccoVeille]

Nice PR! We just need to de-embed the OpenAPIServerConfig field.

I thought 84ee2ff would come with a change on the struct to de-embed it really. Here you de-embedded the way the embedded struct is called.

But maybe I'm missing something

[dylanhitt]

I thought 84ee2ff would come with a change on the struct to de-embed it really. Here you de-embedded the way the embedded struct is called.

Maybe I'm just misunderstanding the ask. I assumed @EwenQuim just wanted it to be structured the way OpenAPIConfig originally was.

The ask was

By doing useless embedding, users will be able to access via s. instead of s.OpenAPIServerConfig. and I think it's not a good thing if ther isn't a good reason to do so (conciseness isn't a good one IMHO).

[ccoVeille]

No, you are fine. I'm sorry. I missed the fact you de-embedded at the struct level