Jezz Santos - 102 - May 7, 2014

More swagger. Lovin it!

I’d like to see if I can document the necessary request headers that certain requests require. One of my API’s requires that callers set a certain request header with certain values (e.g. Basic Auth header). Can swagger document that?

All my API’s are secured by OAuth2.0 Bearer tokens. Does swagger + SS do anything to help consumers create access_tokens using our OAuth Server in order to make the request?

You can use the Swagger Attributes to markup your services and provide more detailed API docs:

I’m not sure if you’ve seen the recent support for Postman that was just released in v4.0.19:

But it supports exporting your session cookies with /postman?exportSession=true which you can use to copy the url into Postman and call services as an authenticated user.

Stefan Tsalapatis:

+Demis Bellot
 the problem with Postman is that customers should download & install it.
This only make it  not a viable option. 
Also we can customize easily  html of swagger .

Jezz Santos:

Oh boy, Postman looks to be another option, but to replace swagger?

I was hoping for a way to do what the swagger petshop demo allows by providing  a page to capture credentials, call the oAuth server to get a token and then feed it into headers of the request.

Are we saying I have to customize swagger-ui myself to do that?

the OAuth providers doesn’t support supplying custom tokens, but since swagger is hosted from the same website, if the user is already authenticated they automatically call services under their existing authenticated session.

Jezz Santos:

Thanks, but in our case, not using the OAuth providers yet. We have our own oAuth server, and it serves tokens for our API.

A potential solution is to provide our own Login dialog on a web page, collect credentials, make the call to create access_token, then feed that into the call the user then makes through swagger UI.
I sort of see a similar experience on the petshop demo.

I guess I am on my own putting these pieces together.