Swashbuckle.WebApi icon indicating copy to clipboard operation
Swashbuckle.WebApi copied to clipboard

Can't add extended data outside of "Info" section

Open MikeGriffinReborn opened this issue 4 years ago • 1 comments

If you look at the Redoc Live sample @ https://redocly.github.io/redoc/ you can see that they have added the Models section and sort of "reordered" the display format. They do this by adding some data just below the SWAGGER "Info" section, for instance:

Please note, this is outside of the "Info" section ...

"tags": [
  {
	 "name": "store_model",
	 "x-displayName": "The Order Model",
	 "description": "<SchemaDefinition schemaRef=\"#/components/schemas/Order\" exampleRef=\"#/components/examples/Order\" showReadOnly={true} showWriteOnly={true} />\n"
  }
],
"x-tagGroups": [
  {
	 "name": "Models",
	 "tags": [
		"pet_model",
		"store_model"
	 ]
  }
]

I can write out the correct JSON like this, however, it's in the "Info" section of the Swagger document. It works because if I manually copy it to the proper section it displays properly.

c.SwaggerDoc("v1", new OpenApiInfo
{
    Title = "My API",
    Version = "v1",
    Description = description,
    Extensions = new Dictionary<string, IOpenApiExtension>
    {
        ["tags"] = new OpenApiArray
        {
            new OpenApiObject
            {
                ["name"] = new OpenApiString("hub_model"),
                ["x-displayName"] = new OpenApiString("The Hub Model"),
                ["description"] = new OpenApiString("<SchemaDefinition schemaRef=\"#/components/schemas/Hub\" exampleRef=\"#/components/examples/Hub\" showReadOnly={true} showWriteOnly={true} />")
            }
        },
        ["x-tagGroups"] = new OpenApiArray
        {
            new OpenApiObject
            {
                ["name"] = new OpenApiString("Models"),
                ["tags"] = new OpenApiArray
                {
                    new OpenApiString("hub_model")
                }
            }
        }
    }
});

How can I get the JSON as shown above to write outside of the "Info" section of the swagger.sjon file?

MikeGriffinReborn avatar Mar 25 '20 19:03 MikeGriffinReborn

Use a DocumentFilter to modify any part of the swagger.json file.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = description,
        Extensions = new Dictionary<string, IOpenApiExtension>
        {
            ["tags"] = new OpenApiArray
            {
                new OpenApiObject
                {
                    ["name"] = new OpenApiString("hub_model"),
                    ["x-displayName"] = new OpenApiString("The Hub Model"),
                    ["description"] = new OpenApiString("<SchemaDefinition schemaRef=\"#/components/schemas/Hub\" exampleRef=\"#/components/examples/Hub\" showReadOnly={true} showWriteOnly={true} />")
                }
            }
        }
    });
    
    c.DocumentFilter<XTagGroupsDocumentFilter>();
});
/// <summary>
/// ReDoc extension for grouping tags.
/// </summary>
public class XTagGroupsDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Extensions["x-tagGroups"] = new OpenApiArray
        {
            new OpenApiObject
            {
                ["name"] = new OpenApiString("Models"),
                ["tags"] = new OpenApiArray
                {
                    new OpenApiString("hub_model")
                }
            }
        };
    }
}

randyburden avatar Jun 02 '23 20:06 randyburden