Swagger UI


Swagger UI是FastAPI内置集成的交互式文档页面,可以查看FastAPI应用所有的路径操作——有哪些路径、什么HTTP方法、收什么参数、返回什么结构,还能直接在页面上发请求测试,功能上类似 Postman、Insomnia 这类 API 测试工具的轻量版(展示和测试API接口)。

Swagger UI页面通过/docs路径进入,以这个简单图书项目为例,开发模式下打开链接http://127.0.0.1:8000/docs就进入了Swagger UI页面。

页面组成

图中显示了项目有一个路径操作,请求方法是GET,请求路径是/books。此外还有其它信息(与FastAPI实例及路由装饰器的参数对应):

  • default 表示标签(tags),文档页给路径操作分组的名字,在装饰器的参数中添加tags=['图书']即可把分组名字换成“图书”,省略tags参数时,标签默认为default。图中相当于@app.get('/books', tags=[])
  • Get All Books表示摘要(summary),是对这个路径操作(API)的一个总结,省略summary参数时FastAPI会根据函数名自动生成摘要,例如处理函数名为get_all_books,自动生成的摘要为Get All Books。图中相当于@app.get('/books', summary='')
  • 左上角的FastAPI表示标题(title),用于介绍该FastAPI应用提供的服务,省略title参数则默认为FastAPI。图中相当于app = FastAPI(title='FastAPI')
  • 标题旁边灰色背景的0.1.0表示版本号(version),表示整个应用的版本号,省略version参数则默认为0.1.0。图中相当于app = FastAPI(version='0.1.0')
  • /openapi.json与default之间的空白处还有一个位置负责表示说明(description),省略时不显示。图中相当于app = FastAPI(description='')
  • description下方是联系方式(contact),包含联系人名(name)、个人或公司网站链接(url)和电子邮件地址(email)。省略时不显示。

    若对FastAPI实例化的代码修改为
    app = FastAPI(contact = {
    	'name': 'chaya',
    	'url': 'https://www.baidu.com',
    	'email': '123456@qq.com'
    })
    

    则页面如下所示

API接口测试

拉开该路径操作,点击“Try it out”。

再点击“Execute”,页面会向服务器发送一个真实的GET请求,并显示响应状态码和内容——相当于在文档页上直接完成了API测试。

点击“Cancel”则退出本次调试状态,页面退出参数填写模式、回到只读的文档视图(返回文档展示模式,不发请求)。

点击“Execute”之后即可查看服务器返回的响应内容。

Swagger UI是通过页面里的JavaScript发送HTTP请求并返回响应,而不是通过curl工具,因为浏览器的安全策略会禁止运行本地命令。这里的curl请求只是JavaScript请求的等价写法,并不是浏览器运行curl命令发送的HTTP请求。

看完后如果想再次发送重新测试,可以点击“Clear”先清空响应内容,清空后再点击“Execute”。

相关链接

笔记-curl

文章摘自:https://www.cnblogs.com/qyly/p/23619352/python-web-framework-fastapi-swagger_ui