Skip to content

Commit

Permalink
Major upgrade to Esmerald 2.0 (#115)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tarsil
tarsil authored Jul 13, 2023
2 parents b9bd968 + 08b2015 commit 70b120d
Show file tree
Hide file tree
Showing 106 changed files with 3,407 additions and 1,792 deletions.
18 changes: 17 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ class World(APIView):
@post(path='/{url}', status_code=status.HTTP_201_CREATED)
async def mars(request: Request, url: str) -> JSONResponse:
...

@websocket(path="/{path_param:str}")
async def pluto(self, socket: Websocket) -> None:
await socket.accept()
Expand Down Expand Up @@ -494,6 +494,22 @@ INFO: Waiting for application startup.
INFO: Application startup complete.
```

## OpenAPI documentation

Esmerald also comes with OpenAPI docs integrated. For those used to that, this is roughly the same and to make it
happen, there were inspirations that helped Esmerald getting there fast.

Esmerald starts automatically the OpenAPI documentation by injecting the OpenAPIConfig default from
the settings and makes Swagger and ReDoc available to you out of the box.

To access the OpenAPI, simply start your local development and access:

* **Swagger** - `/docs/swagger`.
* **Redoc** - `/docs/redoc`.

There are more details about [how to configure the OpenAPIConfig](https://esmerald.dev/configurations/openapi/config.md)
within the documentation.

## Notes

This is just a very high-level demonstration of how to start quickly and what Esmerald can do.
Expand Down
62 changes: 54 additions & 8 deletions docs/application/settings.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,9 +84,6 @@ What just happened?
3. Imported specific database settings per environment and added the events `on_startup` and `on_shutdown` specific
to each.

!!! note
Esmerald supports [Tortoise-ORM](https://tortoise.github.io/) for async SQL databases and therefore has the
`init_database` and `stop_database` functionality ready to be used.

## Esmerald Settings Module

Expand Down Expand Up @@ -268,7 +265,7 @@ very useful for development.
<sup>Default: Same as the Esmerald.</sup>

* **contact** - The contact of an admin. Used for OpenAPI.

<sup>Default: `{"name": "admin", "email": "[email protected]"}`.</sup>

* **terms_of_service** - The terms of service of the application. Used for OpenAPI.
Expand All @@ -284,7 +281,7 @@ very useful for development.
<sup>Default: `None`.</sup>

* **secret_key** - The secret key used for internal encryption (for example, user passwords). We strongly advise to
update this particular setting, mostly if the application uses the native [Tortoise](../databases/tortoise/motivation.md)
update this particular setting, mostly if the application uses the native [Saffier](../databases/saffier/motivation.md)
support.

<sup>Default: `my secret`</sup>
Expand Down Expand Up @@ -363,21 +360,70 @@ application and not only for specific endpoints.

* **reload** - Boolean flag indicating if reload should happen (by default) on development and testing enviroment.
The default environment is `production`.

<sup>Default: `False`</sup>

* **root_path_in_servers** - A Flag indicating if the root path should be included in the servers.

<sup>Default: `True`</sup>

* **openapi_url** - URL of the openapi.json.

<sup>Default: `/openapi.json`</sup>

!!! Danger
Be careful when changing this one.

* **redoc_url** - URL where the redoc should be served.

<sup>Default: `/docs/redoc`</sup>

* **swagger_ui_oauth2_redirect_url** - URL to serve the UI oauth2 redirect.

<sup>Default: `/docs/oauth2-redirect`</sup>

* **redoc_js_url** - URL of the redoc JS.

<sup>Default: `https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js`</sup>

* **redoc_favicon_url** - URL for the redoc favicon.

<sup>Default: `https://esmerald.dev/statics/images/favicon.ico`</sup>

* **swagger_ui_init_oauth** - Python dictionary format with OpenAPI specification for the swagger
init oauth.

<sup>Default: `None`</sup>

* **swagger_ui_parameters** - Python dictionary format with OpenAPI specification for the swagger ui
parameters.

<sup>Default: `None`</sup>

* **swagger_js_url** - URL of the swagger JS.

<sup>Default: `https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js`</sup>

* **swagger_css_url** - URL of the swagger CSS.

<sup>Default: `https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css`</sup>

* **swagger_favicon_url** - URL of the favicon for the swagger.

<sup>Default: `https://esmerald.dev/statics/images/favicon.ico`</sup>

* **password_hashers** - A list of [password hashers](../password-hashers.md) used for encryption of the passwords.

<sup>Default: `["esmerald.contrib.auth.hashers.PBKDF2PasswordHasher",
"esmerald.contrib.auth.hashers.PBKDF2SHA1PasswordHasher"]`
</sup>

!!! warning
The password hashers are linked to [Tortoise](../databases/tortoise/motivation.md) support and are used
The password hashers are linked to [Saffier](../databases/saffier/motivation.md) support and are used
with the models provided by default with Esmerald.

* **routes** - A list of routes to serve incoming HTTP and WebSocket requests.

<sup>Default: `[]`</sup>

!!! tip
Expand Down
4 changes: 2 additions & 2 deletions docs/configurations/jwt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ To use the JWTConfig with a middleware.
```

!!! info
The example uses a supported [JWTAuthMiddleware](../databases/tortoise/middleware.md#jwtauthmiddleware)
from Esmerald with Tortoise ORM.
The example uses a supported [JWTAuthMiddleware](../databases/saffier/middleware.md#jwtauthmiddleware)
from Esmerald with Saffier ORM.

## Parameters

Expand Down
47 changes: 0 additions & 47 deletions docs/configurations/openapi/apiview.md
View file

This file was deleted.

118 changes: 66 additions & 52 deletions docs/configurations/openapi/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,36 @@

OpenAPIConfig is a simple configuration with basic fields for the auto-genmerated documentation from Esmerald.

There are two pieces for the documentation.
Prior to version 2, there were two pieces for the documentation but now it is simplified with a simple
one.

* [OpenAPIConfig](#openapiconfig)
* [OpenAPIView](./apiview.md)

!!! Tip
More information about OpenAPI
<a href="https://swagger.io/" target='_blank'>here</a>.
More information about
<a href="https://swagger.io/" target='_blank'>OpenAPI</a>.

You can create your own OpenAPIConfig and populate all the variables needed or you can simply
override the settings attributes and allow Esmerald to handle the configuration on its own. It
is up to you.

!!! Warning
When passing OpenAPI attributes via instantiation, `Esmerald(docs_url='/docs/swagger',...)`,
those will always be used over the settings or custom configuration.

## OpenAPIConfig and application

The `OpenAPIConfig` **needs** an [OpenAPIView] to make sure it serves the documentation properly.
The `OpenAPIConfig` contains a bunch of simple fields that are needed to to serve the documentation
and those can be easily overwritten.

Currently, by default, it is using the Esmerald OpenAPIView pointing to:
Currently, by default, the URL for the documentation are:

* **Swagger** - `/docs/swagger`.
* **Redoc** - '/docs/redoc`.
* **Redoc** - `/docs/redoc`.

## Parameters

* **create_examples** - Generates doc examples.

<sup>Default: `False`</sup>

* **openapi_apiview** - The [OpenAPIView](./apiview.md) serving the docs.

<sup>Default: `OpenAPIView`</sup>
This are the parameters needed for the OpenAPIConfig if you want to create your own configuration.

* **title** - Title of the API documentation.

Expand All @@ -47,9 +50,7 @@ with OpenAPI or an instance of `openapi_schemas_pydantic.v3_1_0.contact.Contact`

<sup>Default: `Esmerald description`</sup>

* **external_docs** - Links to external documentation. This is an OpenAPI schema external documentation, meaning,
in a dictionary format compatible with OpenAPI or an instance of
`openapi_schemas_pydantic.v3_1_0.external_documentation.ExternalDocumentation`.
* **terms_of_service** - URL to a page that contains terms of service.

<sup>Default: `None`</sup>

Expand All @@ -59,48 +60,74 @@ in a dictionary format compatible with OpenAPI or an instance of

<sup>Default: `None`</sup>

* **security** - API Security requirements information. This is an OpenAPI schema security, meaning,
in a dictionary format compatible with OpenAPI or an instance of
`openapi_schemas_pydantic.v3_1_0.security_requirement.SecurityRequirement`

<sup>Default: `None`</sup>

* **components** - A list of OpenAPI compatible `Server` information. OpenAPI specific dictionary or an instance of
`openapi_schemas_pydantic.v3_10_0.components.Components`
* **servers** - A python list with dictionary compatible with OpenAPI specification.

<sup>Default: `None`</sup>
<sup>Default: `[{"url": "/"}]`</sup>

* **summary** - Simple summary text.

<sup>Default: `Esmerald summary`</sup>

* **security** - API Security requirements information. This is an OpenAPI schema security, meaning,
in a dictionary format compatible with OpenAPI or an instance of
`openapi_schemas_pydantic.v3_1_0.security_requirement.SecurityScheme`

<sup>Default: `None`</sup>

* **tags** - A list of OpenAPI compatible `Tag` information. This is an OpenAPI schema tags, meaning,
in a dictionary format compatible with OpenAPI or an instance of `openapi_schemas_pydantic.v3_1_0.server.Server`.

<sup>Default: `None`</sup>

* **terms_of_service** - URL to a page that contains terms of service.
* **root_path_in_servers** - A Flag indicating if the root path should be included in the servers.

<sup>Default: `True`</sup>

* **openapi_url** - URL of the openapi.json.

<sup>Default: `/openapi.json`</sup>

!!! Danger
Be careful when changing this one.

* **redoc_url** - URL where the redoc should be served.

<sup>Default: `/docs/redoc`</sup>

* **swagger_ui_oauth2_redirect_url** - URL to serve the UI oauth2 redirect.

<sup>Default: `/docs/oauth2-redirect`</sup>

* **redoc_js_url** - URL of the redoc JS.

<sup>Default: `https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js`</sup>

* **redoc_favicon_url** - URL for the redoc favicon.

<sup>Default: `https://esmerald.dev/statics/images/favicon.ico`</sup>

* **swagger_ui_init_oauth** - Python dictionary format with OpenAPI specification for the swagger
init oauth.

<sup>Default: `None`</sup>

* **use_handler_docstrings** - Flag enabling to read the information from a [handler](../../routing/handlers.md)
docstring if no description is provided.
* **swagger_ui_parameters** - Python dictionary format with OpenAPI specification for the swagger ui
parameters.

<sup>Default: `None`</sup>

<sup>Default: `False`</sup>
* **swagger_js_url** - URL of the swagger JS.

* **webhooks** - A mapping of key to either an OpenAPI `PathItem` or an OpenAPI `Reference` instance. Both PathItem and
Reference are in a dictionary format compatible with OpenAPI or an instance of
`openapi_schemas_pydantic.v3_1_0.path_item.PathItem` or `openapi_schemas_pydantic.v3_1_0.reference.Reference`.
<sup>Default: `https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js`</sup>

<sup>Default: `False`</sup>
* **swagger_css_url** - URL of the swagger CSS.

* **root_schema_site** - Static schema generator to use for the "root" path of `/schema/`.
<sup>Default: `https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css`</sup>

<sup>Default: `redoc`</sup>
* **swagger_favicon_url** - URL of the favicon for the swagger.

* **enabled_endpoints** - A set of the enabled documentation sites and schema download endpoints.
<sup>Default: `https://esmerald.dev/statics/images/favicon.ico`</sup>

<sup>Default: `{"redoc", "swagger", "elements", "openapi.json", "openapi.yaml"}`</sup>

### How to use or create an OpenAPIConfig

Expand All @@ -113,20 +140,12 @@ It is very simple actually.
This will create your own `OpenAPIConfig` and pass it to the Esmerald application but what about changing the current
default `/docs` path?

You will need an [OpenAPIView](./apiview.md) to make it work.

Let's use a an example for clarification.

```python title='myapp/openapi/views.py'
```python
{!> ../docs_src/configurations/openapi/apiview.py!}
```

Then you need to add the new APIView to your OpenAPIConfig.

```python title='src/app.py'
{!> ../docs_src/configurations/openapi/example2.py!}
```

From now on the url to access the `swagger` and `redoc` will be:

* **Swagger** - `/another-url/swagger`.
Expand All @@ -141,11 +160,6 @@ settings.
{!> ../docs_src/configurations/openapi/settings.py!}
```

!!! Warning
We did import the `MyOpenAPIView` inside the property itself and the reason for it is to avoid import errors
or any `mro` issues. Since the app once starts runs the settings once, there is no problem since it will not
reconfigure on every single request.

Start the server with your custom settings.

```shell
Expand Down
Loading

0 comments on commit 70b120d

Please sign in to comment.