mirror of https://github.com/tiangolo/fastapi.git
fix(extending-openapi.md): fix hl lines for tutorial006
This commit is contained in:
Shahar Ilany
parent
75d33426e7
commit
45f749d827
|
|
@ -1,7 +1,7 @@
|
|||
# Extending OpenAPI
|
||||
|
||||
!!! warning
|
||||
This is a rather advanced feature. You probably can skip it.
|
||||
This is a rather advanced feature. You probably can skip it.
|
||||
|
||||
If you are just following the tutorial - user guide, you can probably skip this section.
|
||||
|
||||
|
|
@ -17,7 +17,7 @@ The normal (default) process, is as follows.
|
|||
|
||||
A `FastAPI` application (instance) has an `.openapi()` method that is expected to return the OpenAPI schema.
|
||||
|
||||
As part of the application object creation, a *path operation* for `/openapi.json` (or for whatever you set your `openapi_url`) is registered.
|
||||
As part of the application object creation, a _path operation_ for `/openapi.json` (or for whatever you set your `openapi_url`) is registered.
|
||||
|
||||
It just returns a JSON response with the result of the application's `.openapi()` method.
|
||||
|
||||
|
|
@ -27,11 +27,11 @@ If it doesn't, it generates them using the utility function at `fastapi.openapi.
|
|||
|
||||
And that function `get_openapi()` receives as parameters:
|
||||
|
||||
* `title`: The OpenAPI title, shown in the docs.
|
||||
* `version`: The version of your API, e.g. `2.5.0`.
|
||||
* `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.0.2`.
|
||||
* `description`: The description of your API.
|
||||
* `routes`: A list of routes, these are each of the registered *path operations*. They are taken from `app.routes`.
|
||||
- `title`: The OpenAPI title, shown in the docs.
|
||||
- `version`: The version of your API, e.g. `2.5.0`.
|
||||
- `openapi_version`: The version of the OpenAPI specification used. By default, the latest: `3.0.2`.
|
||||
- `description`: The description of your API.
|
||||
- `routes`: A list of routes, these are each of the registered _path operations_. They are taken from `app.routes`.
|
||||
|
||||
## Overriding the defaults
|
||||
|
||||
|
|
@ -132,17 +132,17 @@ You can probably right-click each link and select an option similar to `Save lin
|
|||
|
||||
**Swagger UI** uses the files:
|
||||
|
||||
* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4/swagger-ui-bundle.js" class="external-link" target="_blank">`swagger-ui-bundle.js`</a>
|
||||
* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4/swagger-ui.css" class="external-link" target="_blank">`swagger-ui.css`</a>
|
||||
- <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4/swagger-ui-bundle.js" class="external-link" target="_blank">`swagger-ui-bundle.js`</a>
|
||||
- <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4/swagger-ui.css" class="external-link" target="_blank">`swagger-ui.css`</a>
|
||||
|
||||
**ReDoc** uses the file:
|
||||
|
||||
* <a href="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js" class="external-link" target="_blank">`redoc.standalone.js`</a>
|
||||
- <a href="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js" class="external-link" target="_blank">`redoc.standalone.js`</a>
|
||||
|
||||
**Stoplight Elements** uses the files:
|
||||
|
||||
* <a href="https://unpkg.com/@stoplight/elements/web-components.min.js" class="external-link" target="_blank">`web-components.min.js`</a>
|
||||
* <a href="https://unpkg.com/@stoplight/elements/styles.min.css" class="external-link" target="_blank">`styles.min.css`</a>
|
||||
- <a href="https://unpkg.com/@stoplight/elements/web-components.min.js" class="external-link" target="_blank">`web-components.min.js`</a>
|
||||
- <a href="https://unpkg.com/@stoplight/elements/styles.min.css" class="external-link" target="_blank">`styles.min.css`</a>
|
||||
|
||||
After that, your file structure could look like:
|
||||
|
||||
|
|
@ -161,8 +161,8 @@ After that, your file structure could look like:
|
|||
|
||||
### Serve the static files
|
||||
|
||||
* Import `StaticFiles`.
|
||||
* "Mount" a `StaticFiles()` instance in a specific path.
|
||||
- Import `StaticFiles`.
|
||||
- "Mount" a `StaticFiles()` instance in a specific path.
|
||||
|
||||
```Python hl_lines="8 12"
|
||||
{!../../../docs_src/extending_openapi/tutorial002.py!}
|
||||
|
|
@ -204,15 +204,15 @@ To disable them, set their URLs to `None` when creating your `FastAPI` app:
|
|||
|
||||
### Include the custom docs
|
||||
|
||||
Now you can create the *path operations* for the custom docs.
|
||||
Now you can create the _path operations_ for the custom docs.
|
||||
|
||||
You can re-use FastAPI's internal functions to create the HTML pages for the docs, and pass them the needed arguments:
|
||||
|
||||
* `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`.
|
||||
* `title`: the title of your API.
|
||||
* `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default.
|
||||
* `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. This is the one that your own app is now serving.
|
||||
* `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. This is the one that your own app is now serving.
|
||||
- `openapi_url`: the URL where the HTML page for the docs can get the OpenAPI schema for your API. You can use here the attribute `app.openapi_url`.
|
||||
- `title`: the title of your API.
|
||||
- `oauth2_redirect_url`: you can use `app.swagger_ui_oauth2_redirect_url` here to use the default.
|
||||
- `swagger_js_url`: the URL where the HTML for your Swagger UI docs can get the **JavaScript** file. This is the one that your own app is now serving.
|
||||
- `swagger_css_url`: the URL where the HTML for your Swagger UI docs can get the **CSS** file. This is the one that your own app is now serving.
|
||||
|
||||
And similarly for ReDoc...
|
||||
|
||||
|
|
@ -221,15 +221,15 @@ And similarly for ReDoc...
|
|||
```
|
||||
|
||||
!!! tip
|
||||
The *path operation* for `swagger_ui_redirect` is a helper for when you use OAuth2.
|
||||
The _path operation_ for `swagger_ui_redirect` is a helper for when you use OAuth2.
|
||||
|
||||
If you integrate your API with an OAuth2 provider, you will be able to authenticate and come back to the API docs with the acquired credentials. And interact with it using the real OAuth2 authentication.
|
||||
|
||||
Swagger UI will handle it behind the scenes for you, but it needs this "redirect" helper.
|
||||
|
||||
### Create a *path operation* to test it
|
||||
### Create a _path operation_ to test it
|
||||
|
||||
Now, to be able to test that everything works, create a *path operation*:
|
||||
Now, to be able to test that everything works, create a _path operation_:
|
||||
|
||||
```Python hl_lines="49-51"
|
||||
{!../../../docs_src/extending_openapi/tutorial002.py!}
|
||||
|
|
@ -318,7 +318,7 @@ presets: [
|
|||
|
||||
These are **JavaScript** objects, not strings, so you can't pass them from Python code directly.
|
||||
|
||||
If you need to use JavaScript-only configurations like those, you can use one of the methods above. Override all the Swagger UI *path operation* and manually write any JavaScript you need.
|
||||
If you need to use JavaScript-only configurations like those, you can use one of the methods above. Override all the Swagger UI _path operation_ and manually write any JavaScript you need.
|
||||
|
||||
## Configuring Stoplight Elements
|
||||
|
||||
|
|
@ -328,30 +328,30 @@ To configure them, use the `get_stoplight_elements_html` built in function param
|
|||
|
||||
### Custom Stoplight Elements Config
|
||||
|
||||
```Python hl_lines="24-37"
|
||||
```Python hl_lines="15-28"
|
||||
{!../../../docs_src/extending_openapi/tutorial006.py!}
|
||||
```
|
||||
|
||||
- `openapi_url` OpenAPI document URL, supporting `http://`, `https://`, and documents containing `$ref` to other http(s) documents.
|
||||
- `title` The page title
|
||||
- `stoplight_elements_js_url` URL to static JS file.
|
||||
- Default: `"https://unpkg.com/@stoplight/elements/web-components.min.js"`
|
||||
- Default: `"https://unpkg.com/@stoplight/elements/web-components.min.js"`
|
||||
- `stoplight_elements_css_url` URL to static CSS file.
|
||||
- Default: `"https://unpkg.com/@stoplight/elements/styles.min.css"`
|
||||
- Default: `"https://unpkg.com/@stoplight/elements/styles.min.css"`
|
||||
- `stoplight_elements_favicon_url` URL to an image that will be used as the page favicon.
|
||||
- Default: `"https://fastapi.tiangolo.com/img/favicon.png"`
|
||||
- Default: `"https://fastapi.tiangolo.com/img/favicon.png"`
|
||||
- `api_description_document` OpenAPI document, provided as YAML string, JSON string or JavaScript object.
|
||||
- `base_path` Helps when using `RouterOptions.HISTORY` but docs are in a subdirectory like https://example.com/api/elements.
|
||||
- `hide_internal` Pass `True` to filter out any content which has been marked as internal with `x-internal`.
|
||||
- Default: `False`
|
||||
- Default: `False`
|
||||
- `hide_try_it` Pass `True` to hide the <a href="https://meta.stoplight.io/docs/platform/ZG9jOjM2OTM3Mjky-try-it" class="external-link" target="_blank">Try It feature.</a>.
|
||||
- Default: `False`
|
||||
- Default: `False`
|
||||
- `try_it_cors_proxy` Pass the URL of a CORS proxy used to send requests to the Try It feature. The provided url is prepended to the URL of an actual request.
|
||||
- `try_it_credential_policy` Use to fetch the credential policy for the Try It feature
|
||||
- Default: `TryItCredentialPolicyOptions.OMIT`
|
||||
- Default: `TryItCredentialPolicyOptions.OMIT`
|
||||
- `layout` There are two layouts for Elements:
|
||||
- Default: `LayoutOptions.SIDEBAR` Three-column design.
|
||||
- `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already.
|
||||
- Default: `LayoutOptions.SIDEBAR` Three-column design.
|
||||
- `LayoutOptions.STACKED` Everything in a single column, making integrations with existing websites that have their own sidebar or other columns already.
|
||||
- `logo` URL to an image that will show as a small square logo next to the title, above the table of contents.
|
||||
- `router`
|
||||
- Default: `RouterOptions.HISTORY`
|
||||
- Default: `RouterOptions.HISTORY`
|
||||
|
|
|
|||
Loading…
Reference in New Issue