{"id":20837599,"url":"https://github.com/taojy123/eave","last_synced_at":"2025-08-01T19:35:22.309Z","repository":{"id":57425328,"uuid":"198542981","full_name":"taojy123/eave","owner":"taojy123","description":"优雅的接口文档制作工具 | A Restful Api Document Builder For Pythonista","archived":false,"fork":false,"pushed_at":"2021-03-17T02:38:39.000Z","size":682,"stargazers_count":29,"open_issues_count":0,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-31T17:59:02.243Z","etag":null,"topics":["api-documentation-tool","doc","documentation","openapi","python"],"latest_commit_sha":null,"homepage":"https://taojy123.github.io/eave/","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/taojy123.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":"2019-07-24T02:27:44.000Z","updated_at":"2025-01-10T03:35:03.000Z","dependencies_parsed_at":"2022-08-29T22:51:14.871Z","dependency_job_id":null,"html_url":"https://github.com/taojy123/eave","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taojy123%2Feave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taojy123%2Feave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taojy123%2Feave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taojy123%2Feave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taojy123","download_url":"https://codeload.github.com/taojy123/eave/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253144287,"owners_count":21861032,"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":["api-documentation-tool","doc","documentation","openapi","python"],"created_at":"2024-11-18T01:08:04.313Z","updated_at":"2025-05-08T20:29:44.378Z","avatar_url":"https://github.com/taojy123.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eave\n\n优雅的接口文档制作工具\n\n\n![logo](https://raw.githubusercontent.com/taojy123/eave/master/eave/resource/logo.jpg)\n\n\n-----\n\n## 适用对象\n\n- 如果你有编写 Restful API 文档的需求\n- 恰好你日常使用 Python 作为主要的编程语言\n\n**那你值得拥有这款神器！**\n\n\n-----\n\n## 安装\n\n- 要求 `Python` 版本高于 `3.6`\n- 使用 `pip` 命令一键安装\n\n```\npip install eave\n```\n\n-----\n\n## 基础用法\n\n编写脚本，用于生成文档\n\n```python\n# demo.py\n\n# 第1步，引入 eave 包内组件\nfrom eave import Doc, Note, Api, PP, QP, BP\n\n# 也可以使用 * 方式完全引入\nfrom eave import *\n\n\n# 第2步，创建一个 doc 对象，并指定文档的标题和接口调用地址\ndoc = Doc(title='My Api Document', host='www.myapi.com')\n\n\n# 第3步，如果需要的话，为文档添加描述信息，描述信息会出现在标题下方（支持 markdown 语法）\ndoc.description = \"\"\"\nthe content of description is **markdown** format\n1. one point\n2. two point\n3. three point\n\"\"\"\n\n\n# 第4步，如果需要的话，为文档添加一些详细的说明，这些内容会出现在接口目录的下方（支持 markdown 语法）\ndoc.add_note(\n    title=\"note title\",\n    content=\"the content of note is also **markdown** format\"\n)\n\n\n# 第5步，添加一个接口，使用 url method params 等参数进行描述\ndoc.add_api(\n    title='Get all orders of shop',\n    url='/shop/\u003cid\u003e/orders/',\n    method='GET',\n    description='Get all orders of shop, shop admin login required',\n    params=[\n        PP(name='id', description='the id of shop'),\n        QP(name='page', type='integer', default=1),\n        QP(name='page_size', type='integer', default=10),\n    ],\n    response_example=\"\"\"\n{\n    \"page\": 1,\n    \"page_size\": 10,\n    \"data\": [\n        {\n          \"order_id\": \"0021\",\n          \"order_price\": \"120.00\",\n          \"order_name\": \"xxx1\",\n        }\n    ]\n}\n\"\"\"\n)\n\n\n# 继续添加接口，可支持的 method 有 GET POST PUT PATCH DELETE 等\ndoc.add_api(\n    title='Create a product',\n    url='/products/',\n    method='POST',\n    params=[\n        BP(name='name', required=True),\n        BP(name='category', example='food'),\n        BP(name='price', type='float', default=0),\n    ],\n    content_types=['application/json'],\n    body_example=\"\"\"\n{\n    \"name\": \"Sprite 250ml\",\n    \"category\": \"food\",\n    \"price\": 3.5\n}\n\"\"\",\n    tips=\"\"\"some `tips` for this api, also **markdown** format\"\"\"\n)\n\n\n# 第6步，添加文档结尾，markdown 格式\ndoc.ending = \"\"\"\nThis is the end of document, **thankyou**!\n\"\"\"\n\n\n# 第7步，使用 build 方法构建生成文档，最后产出 html 文件\ndoc.build('best.html')\n\n```\n\n\n#### 执行脚本，生成文档 \n\n```\npython demo.py\n```\n\n生成的 `html` 文件可以直接用浏览器（推荐 chrome）打开查看\n\n样式美观、结构合理，效果如下图：\n\n![demo](https://raw.githubusercontent.com/taojy123/eave/master/eave/resource/best.png)\n\n## 进阶操作\n\n```python\n# 指定 language 为 zh，构建中文文档\ndoc.build('best_zh.html', language='zh')\n\n# 自定义文档模版\nimport os\nprint(os.getcwd())\ndoc.template = 'eave/template.html'\ndoc.build('best1.html')\n\n# 将文档对象导出为 json\njson_data = doc.to_json()\n\n# 导入 json 创建文档对象\ndoc2 = Doc(json_data)\ndoc2.title = 'My Second Api Document'\ndoc2.build('best2.html')\n\n# 将文档对象导出为 yaml\nyaml_data = doc.to_yaml()\n\n# 导入 yaml 创建文档对象\ndoc3 = Doc(yaml_data)\ndoc3.build('best3.html')\n\n# 在添加 api 时，也通过 from_md 参数，引入单独编写的 markdown 文件作为文档内容\ndoc.add_api(\n    title=\"获取订单列表接口\",\n    url=\"/orders/list/\",\n    from_md=\"orders.md\",\n)\n```\n\n## 更新说明\n\n#### v0.1.3\n\n- 调整了文档模板，适配手机屏幕\n\n\n#### v0.1.2\n\n- `UriParam` 改为 `PathParam`\n- api 中的 `uri` 改为 `url`\n- api 中的`uri_params` 改为 `path_params`\n- api 中的 `path_params` `query_params` `body_params` 统一为 `params`\n- `path_params` `query_params` `body_params` 现在作为 `property` 出现\n- 文档底部增加打印按钮\n- api 中添加 `make_body_example` 功能，可根据 `body_params` 生成简单示例\n- 添加单元测试 `test.py`\n- utils 中添加支持 `openapi` 导入功能\n- utils 中不再支持 `raml`\n\n`0.1.x` 与前版本 `0.0.x` 不兼容\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaojy123%2Feave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaojy123%2Feave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaojy123%2Feave/lists"}