In Azure API Management Developer Portal, how can I display an openapi request body schema in a friendly format?

1
votes

I'm attempting to publish a API (using json-api formatting) with Azure API Management by uploading my openapi 2.0 (nee. swagger) specification. I want to use APIM's built-in developer portal to serve documentation, but I've run into a bit of a snag with displaying the request body formatting.

The only 'representations' available by default are 'schema' and 'sample'. Sample is useful, but 'schema' just seems to display the 'raw' response schema, which isn't quite as nice as I'd like1. Unfortunately, this seems to be the only way to display the 'description' for a field in a request schema. This isn't ideal, because that description contains important context about some fields.

Ideally, I'd like to display a table with columns identifying the field, their type, and the description from the openapi spec. I originally thought I'd be able to edit the Operation template to parse and render the information from the schema, but it appears to be passed into the template as a string - not an object that I can index into.

Is there a way to present the field descriptions in a 'friendly' way with APIM Developer portal?

Schema Screensot (Since I'm not allowed to post images yet :c)

1
azureazure-api-managementopenapi
The challenge with passing the sample in as an object is that only works if the content type is JSON based. Is it not possible to parse it in JS and render it manually? Sorry, I work on the team but not on the dev portal so I'm only partially useful :-) – Darrel Miller
@DarrelMiller It might be possible, but I don't know how I'd even start to do that with DotLiquid. If there were a way to define custom helpers (like custom filters in django), I could definitely do that. – hoylemd

1 Answers

0
votes

It is possible to present the field descriptions in the way you want. To do it, you will have to customize the Operations template in the developer portal. Here is an example. Look at the sample screenshot there. It renders Request Parameters in table format, rather then Request Body in JSON.