Swagger Issues about frame HOT 13 CLOSED

Btw, I get 401s ok through Postman. Somethings up with Swagger UI, wondering if older build?

[email protected]
[email protected]
[email protected]

Attaching log

from frame.

Am noticing this issue on Authorization header not being passed: hapi-swagger/hapi-swagger#495 -- seems like a versioning issue? Can anyone confirm?

from frame.

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.

from frame.

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.

from frame.

@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.

from frame.

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'.

#221

Happy Trails.

from frame.

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.

from frame.

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.

from frame.

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.

from frame.

Pull request #222 for controlling id params through Swagger now complete. Please review.

from frame.

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.

from frame.

Can we close this since #221 landed?

from frame.

works for me.

from frame.