➕ [FEATURE] Mounting app creates API definition

[aledenza]

Feature

With this MR, if subapp is mounted to mainapp, you will see dropdown with ability to select API definition on the mainapp docs page.

Description

1. Mount the app as shown below

app = FastAPI(title="Main app", servers=[{"url": "http://localhost:8000"}])
@app.get("/app")
def read_main():
    return {"message": "Hello World from main app"}

subapi1 = FastAPI(title="Sub app 1")
@subapi1.get("/sub")
def read_sub():
    return {"message": "Hello World from sub API"}

app.mount("/subapi1", subapi1) # you can specify name of api definition. If not, path used as name

2. Go to http://localhost:8000/docs and you will see this

3. You can select the mounted app API from dropdown

4. Select mounted API and it will appear on the screen

5. ReDoc now comes with same feature

Help wanted / Discussion

Swagger UI comes with API definition feature almost out the box, unlike Redoc, that does not have this feature(or i did not found). So current solution is to use customized Swagger UI top bar with some JS on top of it.

So, if somebody know how to add this feature to redoc properly, I'll really appreciate your help.
Maybe Redoc does ned this feature if there's not native support.

[github-actions]

📝 Docs preview for commit df64be7 at: https://63e2d5b3cd7ae81086b903af--fastapi.netlify.app

[github-actions]

📝 Docs preview for commit 634a3f9 at: https://63e2d6bf5148b610f12ba092--fastapi.netlify.app

[github-actions]

📝 Docs preview for commit f9b6f4d at: https://63e423d881d8b7009f0fd4e7--fastapi.netlify.app

[r0b2g1t]

looks interesting.

[Ryandaydev]

@ZakharovDenis I'd like to understand this PR a bit more. This looks like a nice feature, but I'd like to understand any overhead that comes with it. Does it require any customization of the SwaggerUI libraries? And how does it affect the compatibility with the out-of-the-box swagger UI we include with fastapi? Since a major open source library like SwaggerUI will change at its own pace, we need to keep our use of it pretty vanilla, IMHO. Otherwise we spend our time maintaining compatibility with external libraries rather than innovating fastapi.

[aledenza]

@ZakharovDenis I'd like to understand this PR a bit more. This looks like a nice feature, but I'd like to understand any overhead that comes with it. Does it require any customization of the SwaggerUI libraries? And how does it affect the compatibility with the out-of-the-box swagger UI we include with fastapi? Since a major open source library like SwaggerUI will change at its own pace, we need to keep our use of it pretty vanilla, IMHO. Otherwise we spend our time maintaining compatibility with external libraries rather than innovating fastapi.

@Ryandaydev, thanks for the question.
If we are talking about swaggerUI, it does not require any customization at all. To make this feature available in swaggerUI, we have to:

1. link one more official JavaScript file, which is swagger-ui-standalone-preset.js
2. change layout to SwaggerUIStandalonePreset
3. use urls keyword instead of url in SwaggerUIBundle object initialization

All this steps is something, that, I think, we can call "SwaggerUI API".
So, the main risk, that swaggerUI maintainers will drop this particular API for some reason.

Things become a little bit different if we talk about Redoc. Because Redoc does not have same feature out-of-the-box, i made a little customization to make this available.
So things, that I've done:

1. In HTML I created the topBar which is the same that SwaggerUI creates by itself. So it has same classes, ids and tags
2. Loaded swagger-ui-standalone-preset.js, which is loads CSS with styles required for the topBar.
3. Wrote a tiny JS function that changes OpenAPI file if dropdown value is changed. (Redoc has similar example here https://github.com/Redocly/redoc/blob/gh-pages/examples/multiple-apis/index.html)

The main risk here that the SwaggerUI maintainers will change topBar classes, so new classes will not correspond with classes, that i wrote for custom topBar, and styles will break.

In fact, I think, that the maintainers of SwaggerUI are more likely to change topBar classes than drop the API, but even class changes won't be frequent.

Also, as I mentioned in MR head, I think, that I probably did not found information how to enable same or similar feature for vanilla Redoc.

Also, It's worth mentioning, that if you do not mount any app and use single FastAPI app, the SwaggerUI and Redoc will look like before, without any topBars. So for single application, all behaviour stays same.

If You have any questions, I'm glad to answer.

[Ryandaydev]

Thanks for the explanation, sounds like the new functionality on the swaggerUI doesn't introduce unnecessary customization. On the redocs, like you said it would be better if we didn't have to customize quite so much. How does Swagger describe this functionality in their docs? (Maybe we could find or suggest something similar to the maintainers of redocs.)