Swagger Issues
bmgdev opened this issue · comments
I'm just now getting around to upgrade to the latest release. I'm able to hit "/documentation" ok (see screenshot) and swagger.json looks ok. However, has anyone else noticed:
- all calls to unauthenticated swagger endpoints (at /documentation) return 500s (not the typical 401) through Swagger UI
- there is no Swagger input box/button to enter a Basic authorization header in typical Swagger fashion.
It would appear this last release is broken unless I'm missing something glaringly obvious here?
Also @jedireza I thank you for finally adding Swagger and ditching Lout.
Btw, I get 401s ok through Postman. Somethings up with Swagger UI, wondering if older build?
hapi@17.2.0
hapi-swagger@9.1.1
hapi-auth-basic@5.0.0
Attaching log
Am noticing this issue on Authorization header not being passed: hapi-swagger/hapi-swagger#495 -- seems like a versioning issue? Can anyone confirm?
I'm not using basic-authentication so haven't run into this issue. I think basic authentication should be replaced with session cookies in the boilerplate like Aqua, doesn't make sense to me that folks would want to work around that.
Don't recall if there are the same CSRF issues in stock Frame but that is outlined here in Aqua:
https://github.com/jedireza/aqua/wiki/HTTP-403-forbidden-when-accessing-API-endpoints
Another issue to look out for is this:
hapi-swagger/hapi-swagger#492
I add a host: 'localhost' in the manifest file server config so I can use localhost consistently from docs instead of .local which could cause issues.
I don't have much time to debug this, but something I noticed on the live demo is the URL being used isn't right. This is probably Heroku's internal hostname and port.
@fishmongr thanks for the help here. It turns out it doesn't seem to matter using .local vs localhost. In any case I've added the server.ext as described in the post (now returning localhost urls).
@jedireza if you ran this locally I assume you'd get the same 500s as me with basic auth.
I dug in a bit deeper and found an easy solution for Swagger UI that can be use for basic or bearer auth. 'headers' need to be added to 'validate' on each route. If you add the 'authorization' header, you'll get an input box to place a basic or bearer token from your login. See image:
headers: Joi.object({
'authorization': Joi.string().required()
}).unknown()
For auto adding the authorization header, Swashbuckle for Swagger seems to do the trick, however the above solution is a low friction "fix" for now. Let me know if you want a PR on this.
ok gents, I found a global fix for Basic (or Bearer, JWT, etc) using the header api_key input box. To get the global input box to show, need to add securityDefinitions for Basic in your manifest. The same below can also be applied for JWT (don't pay any attention to the hapi-swagger comment in source that says this is broken):
options: {
securityDefinitions: {
'basic': {
'type': 'apiKey',
'name': 'Authorization',
'in': 'header'
}
},
security: [{ 'basic': [] }],
info: {
title: 'Frame API Documentation',
and voila:
You can still use the method in the post above to protect by route, but ill stick to the global input box. This now unbreaks the default Frame install for Swagger using the basic auth.
I've submitted a PR - note that 'SecurityDefinitions' need to come before 'info'.
Happy Trails.
oi. I just now noticed there are no route params setup so we can pass ids through swagger. We need to do, for example:
server.route({
method: 'GET',
path: '/api/accounts/{id}',
options: {
tags: ['api','accounts'],
description: 'Get a customer account by ID. [Admin Scope]',
notes: 'Get a customer account by ID.',
validate: {
params: {
id : Joi.number()
.required()
.description('the id to get the account'),
}
},
auth: {
scope: 'admin'
}
},
Attached is what it should look like in Swagger. I need to fix all these anyway so look for the next PR.
Ah good find on the global route fix, I forgot about the global route defaults, nice.
Regarding the missing Swagger route params, that is a very topical discussion. I actually submitted the last pull request that filled out all the doc, endpoint, and tag descriptions like 5 days ago here:
#218
Before that /documentation was a ghost town, so pleasure to have someone else jumping in here with Swagger updates on this important framework!
I had some earlier discussions with @jedireza here #217 about a number of Swagger updates including query parameter and response schema. He is on-board but doesn't have time to implement and also has some valid concerns with maintenance and clutter he mentioned there.
Happy to contribute, I've been around Frame for a while now. Great job on the docs, looking solid.
One note regarding docs... given the nature of hapi/frame, it'd be good to keep docs/comments in separate swagger yaml files if we're able to, otherwise we run the risk of bloated routes. I've done this in vanilla swagger-ui but have not investigated this with hapi/frame.
As far as getting these query parameters in/fixed, Swagger is effectively broken without them. If we really want to dial it in, we should figure out why hapi-swagger keeps throwing us this username/password box if hitting an endpoint with no auth... and then check on why debug likes throwing us 500s. It doesnt help that hapi-swagger hasnt been updated in a while, I'll hit that repo next.
Pull request #222 for controlling id params through Swagger now complete. Please review.
One note regarding docs... given the nature of hapi/frame, it'd be good to keep docs/comments in separate swagger yaml files if we're able to, otherwise we run the risk of bloated routes.
I'd like to see what this looks like.
Can we close this since #221 landed?
works for me.