Add custom properties to swagger.json definition file

Add custom properties to swagger.json definition file

  

Hi,

I'm looking for a way to add more information in the swagger.json definition file. 

I need to add multiple HTTP status response to the generated definition. (200 is the only one i can see) and also, add some extended properties (using the "x-") as seen in the specification.

I looked up in the documentation and found out a way to alter the returning status code using the "SetStatusCode" action but it is not reflected in the swagger definition file.

I also found a way to add more properties to the definition by implementing some sort o "middleware" that will grab the platform auto generated definition, add what i need, and return the result to the client, but before i procede on this implementation i would like to know if there is a better way of doing it.

An example of what i need to add (in red) is below:

...

"responses":{  
   "200":{  
      "description":"OK.",
      "schema":{  
         "$ref":"#/definitions/Aluno"
      }
   },
   "404":{  
      "description":"Aluno não encontrado."
   },
   "500":{  
      "description":"Erro interno."
   }

},
"x-mask":{  
   "nascimento":"dd/MM/yyyy"
}

...


Hi Fernando,


Allowing the swagger costumization is indeed in the improvements roadmap for the feature but at this point there is no planned timeline (or even commitment) for it.


In the meanwhile, if you already found a way to do it can you share some details about it here? It would be nice for other developers that have the similar requirements. 


Regards,

João Rosado 

Thank's for clearing my dought João.

Right now I'm trying to test the concept and validate it. When I have something more concrete I'll post it here.


Hi guys, this post is old but I'd like to bring up if this customization of swagger definition is possible now on the Outsystems? thanks.

Solution

Actually, I found a way to extend the swagger definition. I just forgot to post the solution here. Here is how it goes:


First, I added the information I needed on the webservice action description field using a tag and a yaml definition



Then, I've created an eSpace that has two ScreenActions, one to generate the new swagger.json definition and another to generate the new documentation (We will get into detail on this one later on)



When the ScreenAction that generates the new swagger.json definition is called, it grabs the default swagger definition, generated by the outsystems platform, extracts the custom yaml definition from the service description using the OutDoc API, and finally merges the two for the final result (I had to create an extension to merge two jsons)





Since the new swagger.json is not compatible with the outsystems automatic generated documentation, I've created a second ScreenAction, that uses the SwaggerUI default implementation, to generate the newly swagger definition.



There are some improvements and tweekes that could be done, but some of them would depend on the outsystems platform modification. For example, I first wanted to use the comment component to generate the custom definition, but it turns out that outdoc doesn't have acces to them, so I used the description field instead. This would maintain both the new an old documentations active if needed.


I also thought that it would be nice so that I could identify a "SetStatusCode" action call and automatically create the documentation output, but again, I couldn't access this level of detail from the OutDoc API.


Another improvement is to create a rewrite filter so that when the default outsystems documentation is reached, the call would be rewritten to access the new SwaggerUI definition. This one does not depend on outsystems changes and could be done in IIS with the rewrite module for example.


Automatically Include the default Outsystems Platform REST status code responses.


Caching would be something to consider too.


I wanted to transform all this on a forge component, but I really lack time for it.


Anyway, I hope it helps you to solve your problem.

Solution