How do I parametrize a URL for POST using Swagger?

Question

I would like to define the following path using Swagger:

/api/libraries/1234/books

And POST a book to the books collection of library, whose id is 1234.

In the example, I've seen here: https://github.com/swagger-api/swagger-spec/blob/master/examples/v2.0/json/petstore-with-external-docs.json

It shows like, you can specify for example: libraries/{id}/books, but you have to define it as a separate path object.

For example, comparing with libraries, for GET purposes; which will retrieve you a list of libraries.

Is there a way to define a sub path object (for example: under libraries define a sub path of id), and under it a sub path of books; and maybe another sub path of employees?

Answer 1

The short answer is no.

Nesting paths is not supported according to the swagger spec 2.0; you have to define paths independently (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathItemObject).

You can then group a list of resources using tags.

Reason for having atomic paths lies with swaggers strong compliance with the REST specs. In REST resources are linked to independent atomic operations (unlike SOAP/RPC).

Answer 2

Not sure if I understand your question correctly but if you want to define path variables for /api/libraries/1234/books/5678/employees/9999 as an example, the path should look like this:

/api/libraries/{library_id}/books/{book_id}/employees/{employe_id}

in which {library_id}, {book_id} and {employee_id} are path variables.