Swagger first generated service inputs/outputs wrong

When taking a Swagger-first approach to generating a RAD descriptor and associated services, the service input/output signatures are wrong. Typically they are documents named _generatedRequest and/or _generatedResponse and this is wrong. While I can change the service input/output signatures, why should I?

Hi Yunus,

The input/output signatures are generated based on the Swagger Document. However, these are grouped under _generated* as the root element for the services. May I know if you facing any issues because of this?

Thanks,
Sree

Hello Sreekanth,

Many RESTful APIs implement JSON as inputs and outputs. Quite often there is a requirement to have an anonymous array structure for an API. It is not straightforward to implement this because even if I define the swagger correctly, I will get a _generatedResponse document as the service input/output. This is wrong.

I can correct this by manually creating a document list and naming as _generatedResponse, however, the next time I refresh the descriptor, I will lose changes from service input/output.

Regards,

Yunus Aswat.

Hi Yunus,
You should not modify the signature of the generated services otherwise runtime you may end up with some issue which will not be supported. In addition, refreshing the RAD would overwrite your changes, as you mentioned.
Now coming to the fields with the name _generatedRequest and generatedResponse, these are by design and not wrong. One might think it is wrong if they assume that the IS service signature will match exactly with the body parameter and response parameter defined in the swagger document. There are reasons to have the service signature in this way for the runtime to work correctly. for one, there can be anonymous schemas defined as a body. Another parameter names can be same as body parameter name. There are many more and hence we designed to have a unique common name for every request body and response body.
What a user who is implementing the services should ensure that the request would come exactly as defined and the output of the service should match exactly as defined. The runtime is taken care of as per the swagger document.
Sometimes users sending the REST request look at the service signature and try to match them. But no, the client should always send the request as per swagger and expect the response as per swagger, strictly as per the contract. If this is followed, functionality works as expected.

If you are facing any issue, do let us know about that.

Regards,
Aishvarya

1 Like