def test_language(self):
doc = Doc()
api = Api(title='test api', url='/test/', method='POST')
api.body_example = '{}'
doc.apis.append(api)
html_en = doc.build()
html_zh = doc.build(language='zh')
self.assertIn('Contents', html_en)
self.assertIn('Request Body Example', html_en)
self.assertIn('Print This Document', html_en)
self.assertIn('接口目录', html_zh)
self.assertIn('示例请求数据', html_zh)
self.assertIn('打印本文档', html_zh)
def test_response_description(self):
doc = Doc()
api = Api(title='test api', url='/test/', method='POST')
api.response_description = 'return *user* info'
doc.add_api(api)
html = doc.build()
self.assertIn('return <em>user</em> info', html)
def test_tips(self):
doc = Doc()
api = Api(title='test api', url='/test/', method='DELETE')
api.tips = '## Be careful to destroy'
doc.add_api(api)
html = doc.build()
self.assertIn('<div class="endpoint delete">', html)
self.assertIn('<h2>Be careful to destroy</h2>', html)
def test_body_param(self):
doc = Doc()
api = Api(title='test api', url='/test/', method='POST')
bp1 = BodyParam(name='username')
bp2 = BodyParam()
bp2.name = 'password'
api.params = [bp1, bp2]
doc.add_api(api)
html = doc.build()
self.assertIn('<div class="endpoint post">', html)
self.assertIn('<td><code>username</code></td>', html)
self.assertIn('<td><code>password</code></td>', html)
def test_query_param(self):
doc = Doc()
api = Api(title='test api', url='/test/', method='GET')
qp1 = QueryParam()
qp1.name = 'page'
qp1.description = 'page number of list'
qp1.default = 1
api.params.append(qp1)
doc.add_api(api)
html = doc.build()
self.assertIn('<td><code>page</code></td>', html)
self.assertIn('<td>page number of list</td>', html)
self.assertIn('<td>1</td>', html)
def test_path_param(self):
doc = Doc()
api = Api(title='test api', url='/test/<id>/', method='GET')
pp1 = PathParam()
pp1.name = 'id'
pp1.description = 'resource id'
pp1.example = 10
api.params.append(pp1)
doc.add_api(api)
html = doc.build()
self.assertIn('<td><code>id</code></td>', html)
self.assertIn('<td>resource id</td>', html)
self.assertIn('<td>10</td>', html)
def test_body_example(self):
doc = Doc()
api = Api(title='test api', url='/test/', method='POST')
api.body_example = """
{
"username": "******",
"password": "******"
}
"""
doc.add_api(api)
html = doc.build()
self.assertIn('"username": "******"', html)
self.assertIn('"password": "******"', html)
def test_api(self):
doc = Doc()
api = Api()
api.title = "first api"
api.method = "GET"
api.url = "/test1/<id>/"
api.description = "this is the **first** api"
doc.add_api(api)
html = doc.build()
self.assertIn('first api', html)
self.assertIn('<div class="endpoint get">', html)
self.assertIn('/test1/<id>/', html)
self.assertNotIn('<id>', html)
self.assertIn('<strong>first</strong>', html)
def test_note(self):
doc = Doc()
note1 = Note()
note1.title = 'test note1'
note1.content = 'This is the **first** test note'
note2 = Note()
note2.content = 'This note has no title'
doc.add_note(note1)
doc.add_note(note2)
html = doc.build()
self.assertIn('test note1', html)
self.assertIn('This is the <strong>first</strong> test note', html)
self.assertNotIn('note2', html)
self.assertIn('This note has no title', html)
def test_doc(self):
doc = Doc(title='Test Api Document', version='v2')
doc.host = 'http://www.apitest.com'
doc.description = """
this is a test document
- test1
- test2
"""
html = doc.build()
self.assertIn('<h1>Test Api Document</h1>', html)
self.assertIn('<li>Version: <code>v2</code></li>', html)
self.assertIn('<li>Host: <code>http://www.apitest.com</code></li>', html)
self.assertIn('<li>test1</li>', html)
self.assertIn('<li>test2</li>', html)
body_example="""
{
"name": "Sprite 250ml",
"category": "food",
"price": 3.5
}
""",
tips="""some `tips` for this api, also **markdown** format""")
# 第6步，添加文档结尾，markdown 格式
doc.ending = """
This is the end of document, **thankyou**!
"""
# 第7步，使用 build 方法构建生成文档，最后产出 html 文件
doc.build('best.html')
# ========= Advanced Usage =========
# 指定 language 为 zh，构建中文文档
doc.build('best_zh.html', language='zh')
# 自定义文档模版
import os
print(os.getcwd())
doc.template = 'eave/template.html'
doc.build('best1.html')
# 将文档对象导出为 json
json_data = doc.to_json()
3. Model 中的 `verbose_name` 没法反应到文档中
4. Model 中的 `default` 没法反应到文档中
5. 含有 lazytext 的话，生成文档就会出错
6. 没有使用 `components` 进行优化
7. 文档中无法体现 `versioning`
<br><br>
#### 解决方案和思路
1. `get_schema_view` 中传参 `generator_class`，改写 `openapi.SchemaGenerator`
2. `ViewSet` 设定 `schema`，改写 `openapi.AutoSchema`
3. 对 `OpenAPIRenderer` 和 `JSONOpenAPIRenderer` 进行 monkey patch
4. 等待 drf 官方支持或修复，也可以尝试贡献代码
"""
doc.add_api(api)
doc.ending = """
#### 互动竞答
##### 请问，`Swagger2` 同 `OpenAPI3` 的关系与下面几组关系中的那一组最相似?
1. `Django` / `Django REST framework`
2. `RAML` / `raml2html`
3. `Python2` / `Python3`
4. `Python` / `Javascript`
<br>
##### *谢谢大家 后会有期*
"""
doc.build('speech.html', 'zh')