Atom Feed Swagger Examples

[CumpsD]

Swagger Examples

Problem

We use ReDoc + Swashbuckle + Swashbuckle filters to generate our OpenAPI specification and documentation: swagger repo

Some of our endpoints are Atom feeds, which only return XML as a response. An example of this is [SwaggerResponseExample(StatusCodes.Status200OK, typeof(MunicipalitySyndicationResponseExamples))]

This example returns an XML string: MunicipalitySyndicationResponseExamples

Our current setup parses this string as if it is XML and thus encodes it:

In effect, there is nothing wrong with Swashbuckle, it is serialising XML as it is supposed. But there is no way to tell Swashbuckle it should treat the example as a raw string.

Research

We believe this example is set at Swashbuckle.AspNetCore.Filters.ResponseExample.SetSingleResponseExampleForStatusCode

Our current research is to focus on checking if content.Value.Example = xmlExample.Value; already contains the encoded value or not.

If it does, one option might be to allow injecting an ExamplesConverter which has some tricks to deal with our raw strings.

This could be something simple such as inheriting from the current ExamplesConverter and looking for xmlns="http://www.w3.org/2005/Atom" to determine it is an Atom example and not encode it.

[CumpsD]

While debugging this issue, it turns out the issue above already linked to newer Swashbuckle code, which had this commit applied: mattfrear/Swashbuckle.AspNetCore.Filters@140601b

Which in turn should solve the issue about XML serialisation. Upgrading the library is the only work left to do. Which in itself needs some research because it has breaking changes.

After the first upgrade it looks fixed, but in some services it doesn't yet. More debugging is needed.

[CumpsD]

We have to return an XmlElement.

Fixes:

• Display correct xml for sync response example municipality-registry#113
• Display correct xml for sync response example postal-registry#102
• chore(deps-dev): bump husky from 7.0.4 to 8.0.3 streetname-registry#130
• Display correct xml for sync response example address-registry#216
• Display correct xml for sync response example building-registry#186
• Display correct xml for sync response example parcel-registry#127