CODEWITHSUNDEEP
.netservicestackswagger
zlZimon
zlZimon

Reputation: 2489

swagger does not display calls which start with a path parameter

I encountered that when having a route to a path with a path parameter at the beginning, this method is not been display when accessing swagger via swagger-ui.

Example:

[Route("/{Version}/userdata", "GET")]
public class UserData
{
 //...
}

I am also using paths like /v1/getSomeData and /v2/getSomeOtherData which are correctly displayed in the swagger-ui. But there should also be some methods which can have different versions (v1/v2) which I access via the path variable at the beginning of the path.

Is that possible with swagger? Of course I also need to display 2 methods for the the /{Version}/userdata since each version has a different response etc.

Upvotes: 2

Views: 1578

Answers (2)

tom redfern
tom redfern

Reputation: 31780

The swagger 2.0 specification definition for your endpoint will be something like the below:

{
    "paths":{
        "/{Version}/userdata":{
            "get":{
                "produces":[
                    "application/json",
                    "text/json"
                ],
                "parameters":[
                    {
                        "name":"Version",
                        "in":"path",
                        "required":true,
                        "type":"string"
                    }
                ],
                "responses":{
                    "200":{
                        "description":"OK"
                    },
                    etc...
                }
            }
        }
    }
}

So there's nothing intrinsically impossible about defining the endpoint /{Version}/userdata using the swagger specification.

However, the Service Stack swagger generation tooling only supports the swagger 1.2 spec. According to @mythz, who is the technical lead on Service Stack, what you want to do is unsupported using the existing tooling.

If this is the case, and you definitely require a swagger definition for your service, then you can do one of:

  1. change your endpoint route to something which the tooling does support
  2. create your swagger definition manually
  3. change your tooling

In your situation, I think the best thing to do would be to change your endpoint route so that the existing tooling can generate the definition. This means removing the path parameter.

If you can't do this then I would create a swagger 2.0 definition manually. If you need help with this please let me know.

Upvotes: 1

mythz
mythz

Reputation: 143359

Swagger UI groups and displays its routes under the root /path which needs to be a literal path.

Upvotes: 1

Related Questions