{"id":16653000,"url":"https://github.com/meyt/restiro","last_synced_at":"2026-02-15T06:33:24.009Z","repository":{"id":57461573,"uuid":"95980903","full_name":"meyt/restiro","owner":"meyt","description":"RESTful API documentation generator (inline documentation + tests)","archived":false,"fork":false,"pushed_at":"2019-07-24T06:43:50.000Z","size":163,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-28T15:23:06.970Z","etag":null,"topics":["documentation-generator","documentation-tool","python","python-webtest","rest","rest-api","restful","restful-api","webtest"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meyt.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":"2017-07-01T18:23:55.000Z","updated_at":"2019-07-24T06:43:52.000Z","dependencies_parsed_at":"2022-09-26T17:41:01.895Z","dependency_job_id":null,"html_url":"https://github.com/meyt/restiro","commit_stats":null,"previous_names":["meyt/webtest-docgen"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/meyt/restiro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyt%2Frestiro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyt%2Frestiro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyt%2Frestiro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyt%2Frestiro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meyt","download_url":"https://codeload.github.com/meyt/restiro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meyt%2Frestiro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29471941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T05:26:30.465Z","status":"ssl_error","status_checked_at":"2026-02-15T05:26:21.858Z","response_time":118,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["documentation-generator","documentation-tool","python","python-webtest","rest","rest-api","restful","restful-api","webtest"],"created_at":"2024-10-12T09:31:14.910Z","updated_at":"2026-02-15T06:33:23.986Z","avatar_url":"https://github.com/meyt.png","language":"Python","readme":"# RESTiro\n\n[![Build Status](\n    https://travis-ci.org/meyt/restiro.svg?branch=master\n)](\n    https://travis-ci.org/meyt/restiro\n) \n[![Coverage Status](\n    https://coveralls.io/repos/github/meyt/restiro/badge.svg?branch=master\n)](\n    https://coveralls.io/github/meyt/restiro?branch=master\n)\n\nRESTful API documentation generator (inline documentation + tests)\n\n\n## Features\n\n- [x] Inline documentation parser\n- [x] Example recorder middleware\n- [x] Generate documentation in Markdown \n- [x] Generate documentation in HTML \n[[restiro-spa-material](https://github.com/meyt/restiro-spa-material)]\n\n\n## Install\n\n```\n    pip install restiro\n```\n\n## Usage\n\n1. Describe the request in comments, e.g:\n    \n    controller/shelf.py\n    ```python\n    class ShelfController:\n        \n        def post(self):\n            \"\"\"\n            @api {post} /shelf/:shelfId/book Add book into shelf\n    \n            @apiVersion 1\n            @apiGroup Book\n            @apiPermission Noneres\n            \n            @apiParam {String} title\n            @apiParam {String} author\n            @apiParam {DateTime} [publishDate]\n             \n            @apiDescription \n            Here is some description\n            with full support of markdown.\n            \n            - watch this!\n            - and this!\n            - there is a list!\n            \"\"\"\n            return [11, 22, 33]\n    ```\n    \n\n2. Attach `restiro` middleware to your WSGI/HTTP verifier\n    (currently `webtest` supported), e.g:\n    \n    Your project tests initializer:\n    \n    ```python\n    from restiro.middlewares.webtest import TestApp\n    from restiro import clean_examples_dir\n    \n    from my_project import wsgi_app\n    \n    clean_examples_dir()\n    test_app = TestApp(wsgi_app)\n    \n    ```\n\n3. Define responses to capture, e.g:\n\n    ```python\n    \n    def test_shelf(test_app):\n        test_app.get('/shelf/100/book')\n        \n        test_app.delete('/shelf/121/book')\n        \n        test_app.doc = True\n        test_app.post(\n            '/shelf/100/book',\n            json={\n                'title': 'Harry Potter',\n                'author': 'JK. Rowling'\n            }\n        )\n        \n        test_app.doc = True\n        test_app.post(\n            '/shelf/100/book',\n            json={\n                'title': 'Harry Potter2'\n            },\n            status=400\n        )\n    ```\n        \n4. Run tests\n5. Build documentation \n    \n    ```\n    $ restiro a_library\n    ```\n\n    Response will be something like: \n    \n    shelf-{shelf_id}-book-post.md\n    ```markdown\n        #  Add book into shelf\n        \n        ## `POST` `/shelf/:shelfId/book`\n        \n        Here is some description\n        with full support of markdown.\n        \n        - watch this!\n        - and this!\n        - there is a list!\n        \n        \n        ## Parameters\n        \n        ### Form parameters\n        \n        Name | Type | Required | Default | Example | enum | Pattern | MinLength | MaxLength | Minimum | Maximum | Repeat | Description\n        --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---\n        title | String | `True` |  |  |  |  |  |  |  |  | `False` | \n        author | String | `True` |  |  |  |  |  |  |  |  | `False` | \n        publishDate | DateTime | `False` |  |  |  |  |  |  |  |  | `False` | \n        \n        ## Examples\n        \n        ### 200 OK\n        \n        #### Request: \n        \n        ```\n        POST /shelf/100/book\n        Content-Type: application/x-www-form-urlencoded\n        ```\n        ```\n        title=Harry Potter\n        author=JK. Rowling\n        ```\n        \n        #### Response: \n        \n        ```\n        Content-Type: application/json\n        ```\n        ```\n        [11, 22, 33]\n        ```\n        \n        \n        ### 400 Bad Request, missed parameter `author`\n        \n        #### Request: \n        \n        ```\n        POST /shelf/100/book\n        Content-Type: application/x-www-form-urlencoded\n        ```\n        ```\n        title=Harry Potter2\n        ```\n        \n        #### Response: \n        \n        ```\n        Content-Type: application/json\n        ```\n        ```\n        {\"message\": \"Missed parameter `author`\"}\n        ```\n        \n        ---\n    ```\n    \n    \n## CLI\n\n```\nusage: restiro [-h] [-t TITLE] [-o OUTPUT] [-b BASE_URI]\n               [-g {markdown,json,spa_material,mock}] [-l LOCALES]\n               [--build-gettext [BUILD_GETTEXT]]\n               src\n\nRestiro Builder\n\npositional arguments:\n  src                   Project module name\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -t TITLE, --title TITLE\n                        Project title\n  -o OUTPUT, --output OUTPUT\n                        Output directory\n  -b BASE_URI, --base-uri BASE_URI\n                        Base URI\n  -g {markdown,json,spa_material,mock}, --generator {markdown,json,spa_material,mock}\n                        Generator, default: markdown\n  -l LOCALES, --locales LOCALES\n                        Locales directory\n  --build-gettext [BUILD_GETTEXT]\n                        Build .POT templates\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeyt%2Frestiro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeyt%2Frestiro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeyt%2Frestiro/lists"}