Core: [builtin swagger-like ui] Ability to set auth header

[karser]

I recently discovered "builtin API Platform documentation". Unfortunately, there is no documentation about this part.
I wonder if it's possible specifying auth config in order to make api calls on the sandbox tab, like we did that in NelmioDocs:

nelmio_api_doc:
    sandbox:
        authentication:
            name: authorization
            delivery: http
            type: bearer

The outcome is smth like Authorization: Bearer <token>

[teohhanhui]

It is [Swagger UI[(https://github.com/swagger-api/swagger-ui).

It looks like there's no such functionality built-in, but there's swaggerUi.api.clientAuthorizations where we should be able to add it.

[teohhanhui]

But I think it's better if this can be added in Swagger UI itself.

[karser]

Thanks @teohhanhui I see, it has to do with the headers parameters
Does api:swagger:dump also dump custom operations, including parameters? Is there builtin annotation NelmioApiDoc-like (e.g @ApiDoc())?

[Simperfit]

api:swagger:dump dumps the same thing as the built-in documentation since it's using the same method. There are no ApiDoc in api-platform. Why do you want that ?

[dkarlovi]

Swagger UI already supports existing OAuth2 and API Key based auth, I have it working with API platform currently with FOSOAuthServerBundle.

API Platform itself does NOT generate the required securityDefinitions and security blocks which should probably somehow get generated if a compatible bundle is recognized. I've had to decorate the Swagger documentation normalizer as in #762 .

Also, you need to call initOauth() in the Twig template yourself.

[Simperfit]

What can we do here ?

[dkarlovi]

@Simperfit here's a short recap, it's not a small feat, but it's most future-proof as it reuses all the SwaggerUI+OAuth existing integration and they'll probably maintain it going further:

• recognize FOS OAuth bundle is installed, what the auth and token URLs are (should be able to fetch from it?) and how it's setup (inspect firewall?)
• add this to generated Swagger:

securityDefinitions: { OauthSecurity: { type: "oauth2", flow: "implicit", # from FOSOauthBundle authorizationUrl: "http://example.com/oauth/v2/auth", tokenUrl: "http://example.com/oauth/v2/token" } }, security: [ { OauthSecurity: [] } ]

• add a way to create an initial "local OAuth client" which is on the same domain as the API, this will enable you to auto-create access tokens for local users, store ID to config
• add this to SwaggerUI.onComplete in the Twig file:

if(typeof initOAuth == "function") { initOAuth({ # from config clientId: "<local OAuth client ID>", realm: "<realm>", appName: "<app>" }); }

• (this is the worst part and I don't like it, but have not found a workaround) create a route which spits out o2c.html, it defaults to /api/o2c.html, but you can have it wherever (it's configurable).

After this, your SwaggerUI will have a login button on all protected API endpoint with an overlay etc where you can login, fetch the access token and start using the API, without copy/pasting anything.

[Simperfit]

@dkarlovi Can you make a PR for this feature ?

[dkarlovi]

@Simperfit doing this whole thing is not a small undertaking, we need (to recap):

1. a "bundle installed and configured" recognizer for OAuth bundle (which would need to become "officially supported")
2. a way to recognize which routes are protected by OAuth (this could probably go to OAuth bundle)
3. a way to generate a "local" OAuth client and know its ID (this could probably go to OAuth bundle)
4. a significant upgrade for Swagger definition generator (which I've semi-successfully tried to do in #762) which should output securityDefinitions and security blocks based on info retrieved from 1) and 2)
5. enable Swagger UI OAuth integration (Twig template change, o2c.html route), this seems like the smallest part

I'm definetly interested in this feature and think the Platform would benefit from it, but cannot pledge to do the entire thing, I can try and do one or two of those.

[dunglas]

In a first time, maybe can we just define a Twig block to allow to easily customize the template.

[dkarlovi]

@dunglas you still need the security definitions in Swagger doc for it to work.

[dunglas]

@dkarlovi you can already do that using the swagger_contect attribute in the @ApiResource annotation.

[dkarlovi]

Great, I'll have to try that out, thanks! 👍

[Simperfit]

@dkarlovi is this fixed ?

[dkarlovi]

I believe so, with 2.1. I have yet to test it, though, hopefully this weekend.

[dkarlovi]

@Simperfit I'm just testing this out on an existing project, have no idea what redirect URL to use / how to tweak it? Do you support implicit flow?

ie. I'm using this:

api_platform:
    oauth:
        enabled: true
        flow: implicit
        clientId: "%swagger.oauth.client%"

If I use Authorize on Swagger UI page, it pushes me to

http://127.0.0.1:8000/oauth/v2/auth?response_type=token&client_id=f8fd39c5-638f-40fc-b380-2979206b9318_rand00m&redirect_uri=http%3A%2F%2Flocalhost%3A3200%2Foauth2-redirect.html&state=TW9uIEp1biAxMiAyMDE3IDE2OjQ4OjA4IEdNVCswMjAwIChDRVNUKQ%3D%3D&realm=oauth2

which works, but redirect URI is http://localhost:3200/oauth2-redirect.html for some reason, I guess that's defaulted on by Swagger UI? This URL is not being served by API Platform currently.

It can be customized, as seen in the docs (oauth2RedirectUrl).

[dkarlovi]

Application flow seems to work, it depends if you want to support implicit flow here too, as Swagger UI seems to.

[Simperfit]

What can we do for this ? to customize to something ?

[dkarlovi]

@Simperfit it boils down to:

1. have oauth2-redirect.html rendered at some $URL (this should probably be something provided by API Platform)
2. set oauth2RedirectUrl=$URL in initOauth(), this should mean you get redirected to that $URL after auth, ie. /oauth/v2/auth?redirect_uri=$URL

After that, implicit flow should work out of the box. I'd try it out, but have to figure out how to modify initOauth() call to supply oauth2RedirectUrl

[Simperfit]

If you would like to submit a PR since you looked into it that would be awsome ! @dkarlovi

[dkarlovi]

BTW you probably should support implicit flow because application flow is application to application login, you might want to allow specific users to login (for example, to test their permissions).

[Simperfit]

Anyway this seems fixed ;)

We may have to improve it a little bit.

[dkarlovi]

@Simperfit I'm looking at this again trying to get implicit flow to work on 2.1.

It seems everything is pretty much the same as suggested in https://github.com/api-platform/core/issues/779#issuecomment-308443352:

1. I've placed oauth2-redirect.html in my bundle's (extending API Platform bundle) public folder so it's accessible as any regular static resource. This file should be copied along Swagger UI bundle.
2. adding this to init-swagger-ui.js _(I don't know how to properly figure out URL here, pass it from DocumentationNormalizer? Seems wrong):_

  const ui = SwaggerUIBundle({
    // ... same

    // this value should contain complete URL to static HTML file from 1)
    oauth2RedirectUrl: data.oauth.redirect_uri
  });

1. config as follows

api_platform:
    oauth:
        enabled: true
        flow: implicit
        clientId: "%swagger.oauth.client%"

This works and shouldn't be a problem to add as a PR, just don't know about 2), what would be a good place to do it?

[dkarlovi]

Note, currently access to OAuth2-based APIs will not work in SwaggerUI v3.