REST Expose - Additional information in Swagger

Hi,

We are exposing a REST API in OutSystems to be consumed by external parties and there are requirements to have a Swagger file that has several fields that OutSystems doesn't populate by default:

  1. Responses (e.g. 400, 204 appearing with an example, OutSystems only creates the default 200, even if no content)
  2. Summary for endpoints
  3. Tags

Is there a way to enrich the Swagger generated by OutSystems? Have you had this use case and come up with a solution to post-process the swagger so that it is not necessary to manually update it? 

Regards,

João Mateus

Solution

Answering my own question.

We ended up using an API management service (in this case Azure) to consume the initial OutSystems swagger and then enriching the operations and definitions in that platform.

Some of the customizations (not possible in OutSystems) we added were:

  • Tags
  • Summary
  • Authentication
  • Responses (OutSystems always sets the response as 200, doesn't show the 400 with the error structure)
  • Examples
  • Servers

Hello João, 

I don't believe there is a way to enrich the Swagger in a programable fashion. You can however use the "Description" field of the exposed API to pass relevant information so it shows up in the automated Outsystems documentation. 

For more information please read this.

Hope it helps!

Paulo Rosário

Solution

Answering my own question.

We ended up using an API management service (in this case Azure) to consume the initial OutSystems swagger and then enriching the operations and definitions in that platform.

Some of the customizations (not possible in OutSystems) we added were:

  • Tags
  • Summary
  • Authentication
  • Responses (OutSystems always sets the response as 200, doesn't show the 400 with the error structure)
  • Examples
  • Servers
Community GuidelinesBe kind and respectful, give credit to the original source of content, and search for duplicates before posting.