# chalice-spec
[](https://github.com/TestBoxLab/chalice-spec/actions/workflows/test.yml)
[](https://github.com/psf/black)
**Chalice × APISpec × Pydantic plug-ins**
Combines the power of Chalice, APISpec, and Pydantic to make AWS Chalice apps easily documented
## Installation
First, add chalice-spec:
```shell
poetry add chalice_spec
```
We consider Chalice, APISpec, and Pydantic "peer dependencies." We only include them as dev
dependencies in our codebase, and you may need to install them in yours if you haven't
already.
```shell
poetry add chalice apispec pydantic
```
## Setup
chalice-spec provides a subclass of the main `Chalice` class, called `ChaliceWithSpec`.
Here is an example of how to get started:
Before:
```python
from chalice import Chalice
app = Chalice(app_name="hello_world")
```
After:
```python
from chalice_spec import ChaliceWithSpec, PydanticPlugin
from apispec import APISpec
spec = APISpec(...,
plugins=[PydanticPlugin()])
app = ChaliceWithSpec(app_name="hello_world", spec=spec)
```
If you use
```python
ChaliceWithSpec(..., generate_default_docs=True)
```
the plugin will generate empty docs (with empty request and response schemas) for every endpoint that you've defined in your app. This can be useful as a starting point / overview while developing.
## Usage
To document your API, use your existing Pydantic models and add kwargs to Chalice decorators.
**Before:**
```python
@app.route('/', methods=["POST"])
def example():
body = MySchema.parse_obj(app.current_request.json_body)
```
**After:**
```python
@app.route('/', methods=["POST"], docs=Docs(
post=Operation(request=MySchema)
))
def example():
body = MySchema.parse_obj(app.current_request.json_body)
```
If you have multiple methods supported, you may have something like:
```python
@app.route('/', methods=["POST", "PUT"],
docs=Docs(
post=Operation(request=MyCreateSchema, response=MyReadSchema),
put=Operation(request=MyEditSchema, response=MyReadSchema)
)
def example():
# code goes here
pass
```
## Auto-Generation
### Default Empty Docs
If you use:
```python
ChalicePlugin(generate_default_docs=True)
```
the plugin will generate empty docs (with empty request and response schemas) for every endpoint that you've defined in your app. This can be useful as a starting point / overview while developing.
### Path Parameters
These are inferred from the path itself. Any identifiers inside curly braces in a path is added as a string path parameter for that path. e.g. for the path `/users/{id}/friends/{f_id}`, the path parameters `id` and `f_id` will be added to the spec.
To disable this behaviour, define your own parameters or set them to an empty list:
```python
Operation(request=MySchema, response=MyOtherSchema, parameters=[])
```
### Tags
Tags are used in things like Swagger to group endpoints into logical sets. If you don't supply any tags, chalice-spec will add a tag for each endpoint that is the first segment of the path. e.g. `/users`, `/users/{id}/friends`, and `/users/{id}/posts` will all be tagged with `users`.
To disable this behaviour, define `tags` in your operation (either with the tags you want, or an empty list):
```python
Operation(request=MySchema, response=MyOtherSchema, tags=[])
```
### Summary and Description
Endpoint summaries and descriptions are inferred from the route docstring. The first line of the docstring is used as the summary, and all other lines become the description:
```python
@app.route('/users/{id}', methods=['GET'], docs=Docs(response=UserSchema))
def get_user(id):
"""
Retrieve a user object.
User's can't retrieve other users using this endpoint - only themselves.
"""
```
To disable this behaviour, you can define your own summary/description or set them to empty strings:
```python
Operation(request=MySchema, response=MyOtherSchema, summary='', description='')
```
### API
- [ ] TODO: this section coming soon!
Raw data
{
"_id": null,
"home_page": "https://github.com/TestBoxLab/chalice-spec",
"name": "chalice-spec",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "Chalice,AWS,APIspec,OpenAPI,Pydantic",
"author": "Jake Wood",
"author_email": "jake@testbox.com",
"download_url": "https://files.pythonhosted.org/packages/9f/9e/9b59a6d8547150461e926d862f6db60d7322c002cbe76d8827cd795aae5b/chalice_spec-0.7.0.tar.gz",
"platform": null,
"description": "# chalice-spec\n\n[](https://github.com/TestBoxLab/chalice-spec/actions/workflows/test.yml)\n[](https://github.com/psf/black)\n\n**Chalice \u00d7 APISpec \u00d7 Pydantic plug-ins**\n\nCombines the power of Chalice, APISpec, and Pydantic to make AWS Chalice apps easily documented\n\n## Installation\n\nFirst, add chalice-spec:\n\n```shell\npoetry add chalice_spec\n```\n\nWe consider Chalice, APISpec, and Pydantic \"peer dependencies.\" We only include them as dev\ndependencies in our codebase, and you may need to install them in yours if you haven't\nalready.\n\n```shell\npoetry add chalice apispec pydantic\n```\n\n## Setup\n\nchalice-spec provides a subclass of the main `Chalice` class, called `ChaliceWithSpec`.\nHere is an example of how to get started:\n\nBefore:\n\n```python\nfrom chalice import Chalice\n\napp = Chalice(app_name=\"hello_world\")\n```\n\nAfter:\n\n```python\nfrom chalice_spec import ChaliceWithSpec, PydanticPlugin\nfrom apispec import APISpec\n\nspec = APISpec(...,\n plugins=[PydanticPlugin()])\n\napp = ChaliceWithSpec(app_name=\"hello_world\", spec=spec)\n```\n\nIf you use\n\n```python\nChaliceWithSpec(..., generate_default_docs=True)\n```\n\nthe plugin will generate empty docs (with empty request and response schemas) for every endpoint that you've defined in your app. This can be useful as a starting point / overview while developing.\n\n## Usage\n\nTo document your API, use your existing Pydantic models and add kwargs to Chalice decorators.\n\n**Before:**\n```python\n@app.route('/', methods=[\"POST\"])\ndef example():\n body = MySchema.parse_obj(app.current_request.json_body)\n```\n\n**After:**\n```python\n@app.route('/', methods=[\"POST\"], docs=Docs(\n post=Operation(request=MySchema)\n))\ndef example():\n body = MySchema.parse_obj(app.current_request.json_body)\n```\n\nIf you have multiple methods supported, you may have something like:\n\n```python\n@app.route('/', methods=[\"POST\", \"PUT\"],\n docs=Docs(\n post=Operation(request=MyCreateSchema, response=MyReadSchema),\n put=Operation(request=MyEditSchema, response=MyReadSchema)\n )\ndef example():\n # code goes here\n pass\n```\n\n## Auto-Generation\n\n### Default Empty Docs\n\nIf you use:\n```python\nChalicePlugin(generate_default_docs=True)\n```\nthe plugin will generate empty docs (with empty request and response schemas) for every endpoint that you've defined in your app. This can be useful as a starting point / overview while developing.\n\n### Path Parameters\n\nThese are inferred from the path itself. Any identifiers inside curly braces in a path is added as a string path parameter for that path. e.g. for the path `/users/{id}/friends/{f_id}`, the path parameters `id` and `f_id` will be added to the spec.\n\nTo disable this behaviour, define your own parameters or set them to an empty list:\n\n```python\nOperation(request=MySchema, response=MyOtherSchema, parameters=[])\n```\n\n### Tags\n\nTags are used in things like Swagger to group endpoints into logical sets. If you don't supply any tags, chalice-spec will add a tag for each endpoint that is the first segment of the path. e.g. `/users`, `/users/{id}/friends`, and `/users/{id}/posts` will all be tagged with `users`.\n\nTo disable this behaviour, define `tags` in your operation (either with the tags you want, or an empty list):\n\n```python\nOperation(request=MySchema, response=MyOtherSchema, tags=[])\n```\n\n### Summary and Description\n\nEndpoint summaries and descriptions are inferred from the route docstring. The first line of the docstring is used as the summary, and all other lines become the description:\n\n```python\n@app.route('/users/{id}', methods=['GET'], docs=Docs(response=UserSchema))\ndef get_user(id):\n \"\"\"\n Retrieve a user object.\n User's can't retrieve other users using this endpoint - only themselves.\n \"\"\"\n```\n\nTo disable this behaviour, you can define your own summary/description or set them to empty strings:\n\n```python\nOperation(request=MySchema, response=MyOtherSchema, summary='', description='')\n```\n\n\n### API\n\n- [ ] TODO: this section coming soon!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Chalice x APISpec x Pydantic plug-ins",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/TestBoxLab/chalice-spec",
"Repository": "https://github.com/TestBoxLab/chalice-spec"
},
"split_keywords": [
"chalice",
"aws",
"apispec",
"openapi",
"pydantic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "110bd756d40277a1eebd69ee2760ea7948c48932d875d0ef9d37c3dc1bb745f3",
"md5": "5b47ceff15f755b97dbc49492079a34b",
"sha256": "a9cebb7686e7555d348568f72e7a0ca2b3c400857226d7cfe003342e1e867cf2"
},
"downloads": -1,
"filename": "chalice_spec-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b47ceff15f755b97dbc49492079a34b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 10765,
"upload_time": "2023-08-23T15:53:33",
"upload_time_iso_8601": "2023-08-23T15:53:33.143663Z",
"url": "https://files.pythonhosted.org/packages/11/0b/d756d40277a1eebd69ee2760ea7948c48932d875d0ef9d37c3dc1bb745f3/chalice_spec-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f9e9b59a6d8547150461e926d862f6db60d7322c002cbe76d8827cd795aae5b",
"md5": "a97251697c7a65ff0be7f5b3b19aa365",
"sha256": "0601850b6fa10f1834e3036115d920d14d31c4871431b0bc11971a810fb459c6"
},
"downloads": -1,
"filename": "chalice_spec-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "a97251697c7a65ff0be7f5b3b19aa365",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 10699,
"upload_time": "2023-08-23T15:53:34",
"upload_time_iso_8601": "2023-08-23T15:53:34.813599Z",
"url": "https://files.pythonhosted.org/packages/9f/9e/9b59a6d8547150461e926d862f6db60d7322c002cbe76d8827cd795aae5b/chalice_spec-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 15:53:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TestBoxLab",
"github_project": "chalice-spec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chalice-spec"
}
JSON
