Add more metadata

[JKamsker]

trafficstars

For minimal apis, i miss methods to add descriptions

app
        .DefineApi("People")
        .HasMapping(api =>
        {
            api.MapGet("/api/v{version:apiVersion}/people/{id:int}", (int id) => "Some response")
              .Produces(response => response.Body<WeatherForecast>())
              .Produces(404)
              .HasApiVersion(1.0)
              ;

        });

Produces:

{
    "x-generator": "NSwag v13.15.10.0 (NJsonSchema v10.6.10.0 (Newtonsoft.Json v9.0.0.0))",
    "openapi": "3.0.0",
    "info": {
        "title": "Minimal API",
        "version": "1"
    },
    "servers": [
        {
            "url": "https://localhost:7174"
        }
    ],
    "paths": {
        "/api/v1/people/{id}": {
            "get": {
                "tags": [
                    "people"
                ],
                "operationId": "GetApiV1People",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "format": "int32"
                        },
                        "x-position": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WeatherForecast"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "WeatherForecast": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                    "date": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "temperatureC": {
                        "type": "integer",
                        "format": "int32"
                    },
                    "temperatureF": {
                        "type": "integer",
                        "format": "int32"
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true
                    }
                }
            }
        }
    }
}

In this example i want to be able to add paths.['/api/v1/people/{id}'].get.description and paths.['/api/v1/people/{id}'].get.responses.['200'].description which is currently (6.0.0-preview.2) not possible

[commonsensesoftware]

This will be reverted in Preview 3, which would alleviate this problem. It should be published - soon. 😉 I'll leave this unresolved until you can confirm you're getting the behavior/features you expected.

[JKamsker]

Ahh what? You will remove features? 😵

How would this solve the issue? 💩

[commonsensesoftware]

🤣 HA! No, not quite. After a long discussion and some refactoring, the mechanisms by which you provide intrinsic metadata will be reverted back to how they were/are. You can see what it will look like here in the updated example.

It's less than ideal, but probably the best that can be done for 6.0. Once MapGroup is available in 7.0, then I'm hoping to pair things down even more. 🤞🏽

[commonsensesoftware]

I'm going to call this a 🐞 simply because it didn't do what you expected. As I mentioned, there is a significant refactor in Preview 3 that will address this. Effectively, the API Versioning-specific code for this has been removed and things should now behave the same as any other Minimal API.

Preview 3 is now available and contains the fix for this issue. Review the release notes and updated examples to see how things have changed.

[commonsensesoftware]

6.0 is officially released and has the same setup as in Preview 3. This should feel natural and coherent with how the metadata is applied, even without API Versioning. In .NET 7.0, some improvements will come to streamline things even further. Thanks for reporting the issue.