Hi. I am reverse engineering a possible client/partners’ rest API, recreating it in SS so that I can
a) use my local instance as a proxy API with 1-to-1 message passthrough, and more importantly:
b) generate an OpenAPI definition for importing into Azure API Management / Logic Apps, generate consumer client SDKs etc . The idea is to be able to provide their clients with integrations between Netigate and client, but because Netigate don’t currently provide a Swagger doc, this is a tedious process, so as step one, I am recreating their endpoints based on their documentation so that I can build the OpenApi spec, and go from there.
However, I cannot figure out how to make ServiceStack’s implementation of OpenAPI match their API definition AND also meet the OpenAPI spec. As a demo, I have created a public feature branch on github, where I demonstrate the issue, available here
Basically, because I have to include the PATH params in my servicestack request class, I don’t know how to then make SS generate the BODY part of my swagger/OpenAPI definition correctly, when there are several properties to be included.
This might be straightforward to solve, but I’ve been staring at this for a while now and cannot see a solution? I.e make a ServiceStack request class, which contains properties that are used in path, query AND body?
I cannot find any samples of this either, so if you have and can point me to them, my apologies in advance.
If you spin up that project and go to swagger, you should see a single endpoint, which is supposed to correspond to the netigate API defined here
The thing is, Netigate have path parameters, query parameters AND (critically) multiple properties in the PUT body, and its that last part that causes me issues.
Looking at their API endpoint definition, there is surveyId and sendoutId as path params, which I have included in my AddRespondentRequest class and they appear in the generated OpenAPI documentation correctly.
However, the remaining three properties in that AddRespondentRequest class are causing me problems.
As per their documentation at the above link, Netigate expect two path params, and then input body to look like:
{
"contactDetails": "foo@bar.com",
"sendMail": true,
"backgroundData": [
{
"Key": "12345",
"Value": "Value1"
},
{
"Key": "12346",
"Value": "Value2"
},
{
"Key": "12347",
"Value": "Value3"
}
]
}
However, according to OpenApi 2.0 (which SS is using) I can only have a single property in my request class specified as “body”, which in my case is the
[ApiMember(Name = "backgroundData",
Description = "Remarks: Key = BGDataLabelId, Value = respondent's background data (not empty or null)",
ParameterType = "body",
//DataType = "object",
IsRequired = false
)]
public Dictionary<int, string> backgroundData { get; set; }
but that leaves me with two remaining properties:
[ApiMember(Name = "contactDetails",
Description = "Remarks: Valid email address, SMS recipient or login identifier.",
ParameterType = "query",
DataType = "string",
IsRequired = true
)]
public string contactDetails { get; set; }
[ApiMember(Name = "sendMail",
Description = "Remarks: Indicates whether Netigate should send the survey link to the respondent, or if you distribute it yourself.",
ParameterType = "query",
DataType = "boolean",
IsRequired = true
)]
public bool sendMail { get; set; }
that SHOULD be sent as part of the body, (NOT the query), but that I can’t figure out how to configure (at the moment they are in my class defined as ParameterType=query, which generates a valid OpenApi spec file, using the online validator here) but that spec does NOT correctly/accurately match the intended Netigate documentation and API implementation).