{"id":25418813,"url":"https://github.com/iterait/apistrap","last_synced_at":"2026-04-06T03:36:27.839Z","repository":{"id":33113020,"uuid":"147664105","full_name":"iterait/apistrap","owner":"iterait","description":"A toolkit for safe and simple implementation of HTTP APIs with Flask.","archived":false,"fork":false,"pushed_at":"2022-04-26T08:06:19.000Z","size":359,"stargazers_count":7,"open_issues_count":18,"forks_count":1,"subscribers_count":7,"default_branch":"dev","last_synced_at":"2025-01-15T08:24:31.195Z","etag":null,"topics":["aiohttp","flask","openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iterait.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-06T11:33:47.000Z","updated_at":"2021-12-06T09:54:47.000Z","dependencies_parsed_at":"2022-08-07T20:00:37.445Z","dependency_job_id":null,"html_url":"https://github.com/iterait/apistrap","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iterait%2Fapistrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iterait%2Fapistrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iterait%2Fapistrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iterait%2Fapistrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iterait","download_url":"https://codeload.github.com/iterait/apistrap/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239126674,"owners_count":19586124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiohttp","flask","openapi","swagger"],"created_at":"2025-02-16T18:28:14.057Z","updated_at":"2025-10-16T04:48:38.384Z","avatar_url":"https://github.com/iterait.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apistrap - HTTP API utilities\n\n[![CircleCI](https://circleci.com/gh/iterait/apistrap.png?style=shield\u0026circle-token=6e0633d5636dd5b858dd4db501695e10b16f373f)](https://circleci.com/gh/iterait/apistrap/tree/dev)\n[![Coverage](https://img.shields.io/coveralls/github/iterait/apistrap.svg)](https://coveralls.io/github/iterait/apistrap)\n[![PyPi](https://img.shields.io/pypi/v/apistrap.svg)](https://pypi.org/project/apistrap/)\n[![Development Status](https://img.shields.io/badge/status-Regular-brightgreen.svg?style=flat)]()\n[![Master Developer](https://img.shields.io/badge/master-Jan%20Buchar-lightgrey.svg?style=flat)]()\n\nThis package contains utilities that take care of most of the tedious tasks in the implementation of an HTTP API with \nFlask or AioHTTP:\n\n- request body validation using Pydantic\n- response serialization and validation\n- API documentation generation using OpenAPI v3 specifications (also with Swagger UI)\n\n## Usage\n\nFirst, you need to initialize the extension and bind it to your app.\n\n### Flask\n\n```python\nfrom flask import Flask\nfrom apistrap.flask import FlaskApistrap\napp = Flask(__name__)\noapi = FlaskApistrap()\noapi.init_app(app)\noapi.title = \"Some title for your API\"\noapi.description = \"A description of the API\"\n```\n\nYou will probably want to put this into a separate module so that you can import it in your blueprint files.\n\n**Important**: A big part of the functionality is exposed using decorators on Flask view functions. Make sure that the \nFlask `route()` decorator is always the last applied one (the one on the top). Otherwise, the HTTP handler might not \ncall some of our functions.\n\n### AioHTTP\n\n```python\nfrom aiohttp import web\nfrom apistrap.aiohttp import AioHTTPApistrap\n\noapi = AioHTTPApistrap()\noapi.title = \"Some title for your API\"\noapi.description = \"A description of the API\"\n\nroutes = web.RouteTableDef()\n\n@routes.get(\"/endpoint\")\ndef endpoint(request):\n    return web.Response(text=\"Lorem ipsum\")\n\n\napp = web.Application()\napp.add_routes(routes)\noapi.init_app(app)\n\nweb.run_app(app)\n```\n\nPlease note that this is very similar to how Apistrap works with Flask. All decorators that work with Flask routes work\nthe same with AioHTTP web routes. Also, you still have to put the route decorators on top.\n\nWe also make it possible to read route parameters using function parameters like you would with Flask:\n\n```python\nfrom aiohttp import web\nfrom apistrap.aiohttp import AioHTTPApistrap\n\noapi = AioHTTPApistrap()\nroutes = web.RouteTableDef()\n\n@routes.get(\"/{param_a}/{param_b}\")\ndef endpoint(param_a: str, param_b: int = 5):  # Note that the request parameter is optional\n    return web.Response(text=\"Lorem ipsum\")\n```\n\n### Request Body Parsing\n\n```python\nfrom pydantic import BaseModel\nfrom flask import Flask, jsonify\nfrom apistrap.flask import FlaskApistrap\n\napp = Flask(__name__)\noapi = FlaskApistrap()\noapi.init_app(app)\n\nclass Request(BaseModel):\n    some_field: str\n\n@app.route(\"/\u003cparam\u003e\")\n@oapi.accepts(Request)\ndef view(param: str, request: Request):\n    \"\"\"\n    A description of the endpoint\n    \"\"\"\n    return jsonify({})\n```\n\nIn this example, the request is automatically de-serialized from JSON, validated according to the Schematics model and \npassed to the view function in a parameter with a type annotation that matches that of the Schematics model. If the \nvalidation fails, error 400 is returned with a list of validation errors (the exact format is described in the API \nspecification).\n\nNote that the doc block will be parsed and used in the API specification as a description of the endpoint.\n\n### Response Declaration and Validation\n\n```python\nfrom pydantic import BaseModel\nfrom flask import Flask\nfrom apistrap.flask import FlaskApistrap\n\napp = Flask(__name__)\noapi = FlaskApistrap()\noapi.init_app(app)\n\nclass MyResponse(BaseModel):\n    some_field: str\n\nclass NotReadyResponse(BaseModel):\n    status: str\n\n@app.route(\"/\")\n@oapi.responds_with(MyResponse, code=201)  # Code is optional\n@oapi.responds_with(NotReadyResponse, code=202)\ndef view():\n    return MyResponse(some_field=\"Some value\")\n```\n\nIn this example, the response format is inferred from the model and added to the specification. Also, the return values\nfrom the view function are automatically validated and serialized to JSON. If an undeclared response type or an invalid \nresponse object is encountered, an error (code 500) is returned.\n\n### Working with the Specification File\n\nYou can obtain the OpenAPI specification through `http://yourapi.tld/spec.json`. This file can be used by \nSwagger-related utilities. The specification file can be put under a different URL with \n`oapi.spec_url = '/anything.json'`. By setting `oapi.spec_url` to `None`, you can effectively hide the \nspecification.\n\nThe extension also serves the Swagger UI automatically. You can browse it on `http://yourapi.tld/apidocs/`. You can \nchange the URL of the UI with `oapi.ui_url = \"/docs_url/`. This feature can be turned off completely with \n`oapi.ui_url = None`.\n\n### Organizing Endpoints Using Tags\n\n```python\nfrom flask import Flask, jsonify\nfrom apistrap.flask import FlaskApistrap\n\napp = Flask(__name__)\noapi = FlaskApistrap()\noapi.init_app(app)\n\n@app.route(\"/\")\n@oapi.tags(\"Tag 1\", \"Tag 2\")\ndef view():\n    return jsonify({})\n```\n\nIn this example, you can see how to organize the endpoints in Swagger UI into categories determined by tags.\n\n## Running Tests\n\nIn a cloned repository, run `python setup.py test` after installing both regular and development requirements with \n`pip`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiterait%2Fapistrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiterait%2Fapistrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiterait%2Fapistrap/lists"}