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)
# 第4步，如果需要的话，为文档添加一些详细的说明，这些内容会出现在接口目录的下方（支持 markdown 语法）
doc.add_note(title="note title",
content="the content of note is also **markdown** format")
# 第5步，添加一个接口，使用 url method params 等参数进行描述
doc.add_api(title='Get all orders of shop',
url='/shop/<id>/orders/',
method='GET',
description='Get all orders of shop, shop admin login required',
params=[
PP(name='id', description='the id of shop'),
QP(name='page', type='integer', default=1),
QP(name='page_size', type='integer', default=10),
],
response_example="""
{
"page": 1,
"page_size": 10,
"data": [
{
"order_id": "0021",
"order_price": "120.00",
"order_name": "xxx1",
}
]
}
""")
# 继续添加接口，可支持的 method 有 GET POST PUT PATCH DELETE 等
doc.add_api(title='Create a product',
url='/products/',
method='POST',
APIKey:
type: apiKey
name: api_key
in: header
security:
- BasicAuth
- APIKey
```
{img2('demo_security.png')}
{img2('demo_security2.png')}
<br><br>
参考: https://www.jianshu.com/p/5365ef83252a
"""
doc.add_api(api)
api = Api(method='POST')
api.title = 'Swagger'
api.url = '/OpenAPI 是规范/Swagger 是实现规范的工具'
api.description = f"""
#### 各主流工具
1. `OpenAPI`: 根据规范编写出 `yaml` 或 `json` 文件，然后使用 `Swagger`、`ReDoc` 等渲染出成品文档 <br><br> {img('swagger_logo.png', 200)} <br>
2. `RAML`: 根据规范编写出 `raml` 文件，然后使用 `raml2html` 等渲染出成品文档 <br><br> {img('raml_logo.png', 200)} <br>
3. `API Blueprint`: 根据规范编写出 `markdown` 文件，然后使用 `Aglio`、`snowboard` 等渲染出成品文档 <br><br> {img('apiblueprint_logo.png', 200)} <br>
#### Swagger-UI
```html
<!DOCTYPE html>
<html>
<head>