display docs and endpoints based on user’s scopes

[yeyeric]

First check

• [ X ] I used the GitHub search to find a similar issue and didn't find it.
• [ X ] I searched the FastAPI documentation, with the integrated search.
• [ X ] I already searched in Google "How to X in FastAPI" and didn't find any information.

Description

I’ve read links on medium about how to add login authentication to the /docs page.
I was wondering how I could display only the endpoints which the user is allowed to access to based on his scopes ?

Any idea how to do so?

Thanks

[zamiramir]

I would suggest asking this question on https://github.com/swagger-api/swagger-ui, as this functionality is not available,as far as I know.

[dmontagu]

@yeyeric You'd need to create a custom OpenAPI endpoint function that generates/filters the schema based on the available scopes.

If you look at the top of the FastAPI.setup method, you can see how the built-in spec-generation endpoint works.

It would be more complicated to filter the spec to routes and models used only by endpoints that the current user could access, but should definitely be possible, at least as long as your authentication scheme isn't exceedingly complicated.

If you wanted to take a stab at writing an endpoint that does this, I'd be happy to accept it as a PR to fastapi-utils (and would be happy to help with any tricky parts of the implementation).

[tiangolo]

Yep, as @dmontagu says, you can customize the generated OpenAPI as documented here: https://fastapi.tiangolo.com/advanced/extending-openapi/

[yeyeric]

Thanks all.
I don’t feel up to this development considering my technical skill, and I’ll leave it as it is for now. May be going back into it in a few months if I m more at ease and really feel the need.
Thanks

[dmontagu]

@yeyeric I put in a little bit of work on this, and am hoping to eventually incorporate some version of it into fastapi-utils.

A gist with my work so far is available at https://gist.github.com/dmontagu/7cfcab8ec9f595c58c6ea49b73aea33d (the usage.py file is based on https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/)

One of the challenges is that you need a way to get the list/mapping of available scopes, which isn't provided out of the box by FastAPI. This helps FastAPI be as flexible as possible, but might mean you'd have to put in a little work to write a dependency function that extracts the scopes from the request. Also, depending on your auth logic, the resulting generated schema might not include everything you can access -- I've tried to make the logic as restrictive as possible, so I require all documented scopes in order to include the route in the generated spec. But if you were to implement the logic in such a way that only one of a collection of documented scopes was required, the approach I'm using would be wrong.

(Also, the generated spec would be wrong if there are security checks that do not make use of FastAPI's security scopes infrastructure, as that's how I'm checking whether the request should have access to a specific route.)

The usage.py file in the gist above shows how this might work in a way compatible with the docs linked above.

Before I publish this, I want to put a little more effort into ensuring it is correct (and create some warning-heavy documentation). But I think it should be doable.

---

I may not be able to finish this for a little while, so if anyone wants to take the implementation linked above and run with it, it would be great if you could submit a PR to fastapi-utils if you finish it up!

[tiangolo]

One thing to have in mind about this is that you need to authenticate the user before and apart from the Swagger UI interface. So, even though Swagger UI has integration for authentication with OAuth2, you would be discarding it or going around it.

The next is that you would then be generating a different OpenAPI depending on the user, which is currently not done by FastAPI, I'm not sure there would be an easy way around it, and I'm not sure it would be worth it and the right approach.

But meanwhile, something you can do, is check how to conditionally show or not OpenAPI and the API docs: https://fastapi.tiangolo.com/advanced/conditional-openapi/

If you need to have much more customization for the API docs, you might need to do it apart from what is integrated into FastAPI, extract the generated OpenAPI and expose it in a different way, in some way. But that would be outside of FastAPI.

The other thing to consider is that you might be relying on Security through obscurity which is not great.

Anyway, just some extra thoughts.

Sorry for the long delay! 🙈 I wanted to personally address each issue and they piled up through time, but now I'm checking each one in order.

[github-actions]

Assuming the original need was handled, this will be automatically closed now. But feel free to add more comments or create new issues or PRs.