How to add x-code-samples for ReDoc with Swashbuckle.AspNetCore?

Question

What's the best way to add x-code-samples for ReDoc to swagger.json through Swashbuckle.AspNetCore.Annotations?

EDIT (March 30, 2019)

I hope this is a better explanation. There is a way in Swashbuckle.AspNetCore to add content to the generated swagger.json.

What's documented (Example from GitHub-Page):

[HttpPost]

[SwaggerOperation(
    Summary = "Creates a new product",
    Description = "Requires admin privileges",
    OperationId = "CreateProduct",
    Tags = new[] { "Purchase", "Products" }
)]
public IActionResult Create([FromBody]Product product)

About what I try to achieve

What I'd like to do is something like this:

[MyCustomSwaggerOperation(
    x-code-samples = [
        {
          "lang": "CSharp", 
          "source": "console.log('Hello World');"
        }, 
        {
          "lang": "php",
          "source": ...
        }
    ]
)]
public IActionResult Create([FromBody]Product product)

This question is too subjective for SO we expect users to should post minimal code necessary to recreate a scenario as well as your attempt to solve the issue. General coding and technology advice can be provided on other SE sites. — Chris Schaller, Mar 24 '19 at 23:27
@HelderSepulveda I have, but I couldn't find a way to make it work with annotations, so that I can insert custom x-code-samples for specific methods or classes. As far as I understood, iDocumentFilters are applied after the swagger document has been generated. I don't know how to add customized x-code-samples there. Thank's in advance. — pemibo, Mar 30 '19 at 15:46
I'm not sure why you would need annotations... Just inject what you need with an iDocFilter — Helder Sepulveda, Mar 30 '19 at 15:50
@HelderSepulveda I thought of annotations because of the way Swashbuckle handles Summary, Description, OperationId, Tags, ... I wanted to generate the x-code-samples in a similar way. Also iDocumentFilters are added after the swagger document has been generated and I haven't figured out yet how to apply a specific x-code-sample to a specific operation then. — pemibo, Mar 31 '19 at 09:22

score 2 · Accepted Answer · answered Mar 31 '19 at 13:47

Here is an IDocumentFilter that injects "x-code-samples" to a parameter

public class InjectSamples : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        PathItem path = swaggerDoc.Paths.Where(x => x.Key.Contains("Values")).First().Value;
        path.Post.Parameters.FirstOrDefault().Extensions.Add("x-code-samples", "123456");
    }
}

Yes you could complicate all this with annotations, but "x-code-samples" is not supported out of the box by Swashbuckle, so you will have to create your own and them use it on the iDocFilter.

In the comments you kept pointing out that IDocumentFilters are added after the swagger document has been generated, Yes we want that!

And the generated swagger.json with that looks like this:

"post": {
    "tags": [ "Values" ],
    "operationId": "ApiValuesPost",
    "consumes": [ "application/json" ],
    "produces": [],
    "parameters": [
        {
            "name": "value",
            "in": "body",
            "required": false,
            "schema": { "type": "string" },
            "x-code-samples": "123456"
        }
    ],
    "responses": {
        "200": { "description": "Success" }
    }
}

How to add x-code-samples for ReDoc with Swashbuckle.AspNetCore?

1 Answers1