Add support for OpenAPI SpecificationExtensions to the SwaggerExample.Create method

[TomBruns]

I use this package to create multiple examples for request bodies that contain complex POCO objects, ex:

        public IEnumerable<SwaggerExample<AuthorizePaymentRequestDTO>> GetExamples()
        {
            yield return SwaggerExample.Create(
                name: "AUTH-SchemeCard-USD",
                summary: "Make a payment (in USD) using a Card",
                description: "This example shows a payment Auth request using a Card (plain text)",
                value: new AuthorizePaymentRequestDTO()
                {
                    MerchantCode = @"test",
                    Amount = new Shared.AmountDTO()
                    {
                        Value = 1000,
                        CurrencyCode = Shared.CurrencyCode.USD
                    }
                } 
              );
         }

Would you consider adding support for an Extensions property similar to the one here: OpenApiExample.Extensions Property

This is related to OpenAPI specification extensions

This capability could be used by some portal tools to extend example support to include example specific values for:

• Custom HTTP Header Fields [FromHeader]
• Path parameters [FromRoute]
• Query String parameters [FromQuery]

[mattfrear]

Hi Tom

I'm not familiar with OpenApi specification extensions. What do you mean by "example specific values"? What would you like to accomplish?

[TomBruns]

Hi Matt

From the OpenAPI Spec
Specification Extensions
While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The goal would be to emit something like this into to OpenAPI File

            examples:
              'AUTH: paymentService_Auth_Request_Credit_Debit_Card':
                summary: ECom (Direct) order (AUTHORIZATION or SALE) w/ Credit or Debit Card
                description: This example shows a complete order for the Direct model
                value:
                  merchantCode: US_MERCHANT_CODE
                  callersReferenceId: Sample 1
                  amount:
                    value: 1000
                    currencyCode: USD
                  paymentMethod:
                    type: card/scheme
                    cardNumber: '4111111111111111'
                    cardVerificationCode: '123'
                    expiryMonth: 1
                    expiryYear: 2025
                    cardHolderName: A Cardholder
                  customerData:
                    billingAddress:
                      postalCode: '12345'
                      country: US
                  customerInteractionType: ECOMMERCE
                x-example-extension: 
                  headers: 
                    - idempotencyKey: 00000000-0000-0000-0000-000000000000
                  parameters:
                    - wpTransactionId:  123456

Note the custom extension " x-example-extension: " in the context of this specific example (at the bottom)

[mattfrear]

Thanks for the explanation. It's not something I've needed to use, and I don't really want it to be supported by this filter.

Did you know you can provide examples for headers and querystring parameters via XML comments? Is that what you need?

/// <summary>
/// Test endpoint
/// </summary>
/// <param name="idempotencyKey" example="00000000-0000-0000-0000-000000000000"></param>
/// <param name="wpTransactionId" example="123456"></param>
[HttpGet("api/values/header")]
public void HeaderTest([FromHeader] string idempotencyKey, string wpTransactionId)
{
}

This filter doesn't support adding examples to headers or request parameters, but that is something that could be added.

[TomBruns]

Thanks for the comment about the example tag in the XML Comments.

Relative to: This filter doesn't support adding examples to headers or request parameters, but that is something that could be added.

What if in the case of supplying multiple examples... the sample values for headers or request parameter should be different for each example?

[mattfrear]

What if in the case of supplying multiple examples... the sample values for headers or request parameter should be different for each example?

If I understand your question - that is the point of my existing IMultipleExamplesProvider<T> interface - you provide multiple examples with different values and then the SwaggerUI presents multiple options to view them in a select list.

It works quite well for request body and response body:

I have no idea

1. if multiple examples are supported in the OpenApi spec on request querystring parameters
2. if it is supported by the spec, I have no idea if Swagger UI supports it.
3. If Swagger UI supports it, I have no idea how it would look - maybe it would use a select list too.

Another caveat: I have never used IMultipleExamplesProvider in production myself. Someone else contributed that PR to this project.