Package: chalice-spec
chalice-specChalice × APISpec × Pydantic plug-insCombines the power of Chalice, APISpec, and Pydantic to make AWS Chalice apps easily documentedInstallationFirst, add chalice-spec:poetryaddchalice_specWe 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.poetryaddchaliceapispecpydanticSetupchalice-spec provides a subclass of the mainChaliceclass, calledChaliceWithSpec.
Here is an example of how to get started:Before:fromchaliceimportChaliceapp=Chalice(app_name="hello_world")After:fromchalice_specimportChaliceWithSpec,PydanticPluginfromapispecimportAPISpecspec=APISpec(...,plugins=[PydanticPlugin()])app=ChaliceWithSpec(app_name="hello_world",spec=spec)If you useChaliceWithSpec(...,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.UsageTo document your API, use your existing Pydantic models and add kwargs to Chalice decorators.Before:@app.route('/',methods=["POST"])defexample():body=MySchema.parse_obj(app.current_request.json_body)After:@app.route('/',methods=["POST"],docs=Docs(post=Operation(request=MySchema)))defexample():body=MySchema.parse_obj(app.current_request.json_body)If you have multiple methods supported, you may have something like:@app.route('/',methods=["POST","PUT"],docs=Docs(post=Operation(request=MyCreateSchema,response=MyReadSchema),put=Operation(request=MyEditSchema,response=MyReadSchema))defexample():# code goes herepassAuto-GenerationDefault Empty DocsIf you use: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 ParametersThese 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 parametersidandf_idwill be added to the spec.To disable this behaviour, define your own parameters or set them to an empty list:Operation(request=MySchema,response=MyOtherSchema,parameters=[])TagsTags 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}/postswill all be tagged withusers.To disable this behaviour, definetagsin your operation (either with the tags you want, or an empty list):Operation(request=MySchema,response=MyOtherSchema,tags=[])Summary and DescriptionEndpoint 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:@app.route('/users/{id}',methods=['GET'],docs=Docs(response=UserSchema))defget_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:Operation(request=MySchema,response=MyOtherSchema,summary='',description='')APITODO: this section coming soon!