Swagger是一个基于网络的API文档框架。它被用来为API创建交互式文档，这些API是为特定目的而建立的。与其他文档类型相比，Swagger UI文档享有许多优势。

它是开源的
使你能够创建和分享API文档
允许你测试API

在这篇文章中，我将逐步解释创建Swagger UI文档的过程，以便通过Flask REST API框架中构建的API获得 "Hello World "响应。我将使用Python和YAML文件来实现Swagger UI和API，并给出解释。

作为前提条件，你应该对Flask APIs及其工作原理有一个基本的了解。如果你需要对Flask APIs有一个基本的了解，你可以参考官方的Flask RESTful API文档。

创建Swagger UI文档的步骤

我们将按照以下步骤为一个API函数建立一个Swagger UI文档。

首先，我们将使用Flask web API框架创建API。
接下来，我们将创建一个JSON或YAML文件，在SwaggerUI中实现API功能。
最后，我们将在有API定义的Python程序中调用创建的JSON或YAML文件。

你需要使用pip install安装以下Python包来运行这个例子。

$ pip install Flask
$ pip install flasgger

如果你想在安装时更新模块，你可以使用pip install -U <module_name>，或者如果你使用Python虚拟环境，希望为你的项目安装特定版本的模块，你可以执行pip install <module_name>==<version>，例如，pip install Flask==2.0.0。

但我建议你应该安装最新的版本。下面是我们Python脚本的导入块。

from flask import Flask, request
from flasgger import Swagger, LazyString, LazyJSONEncoder
from flasgger import swag_from

使用Flask方法定义Flask应用。

app = Flask(__name__)

你需要JSON编码器来从API对象创建JSON，为此你可以使用LazyJSONEncoder类。

app.json_encoder = LazyJSONEncoder

Swagger UI文档的模板和配置被定义为如下的字典对象。

swagger_template = dict(
info = {'title': LazyString(lambda: 'My first Swagger UI document'),'version': LazyString(lambda: '0.1'),'description': LazyString(lambda: 'This document depicts a      sample Swagger UI document and implements Hello World functionality after executing GET.'),},host = LazyString(lambda: request.host)
)
swagger_config = {"headers": [],"specs": [{"endpoint": 'hello_world',"route": '/hello_world.json',"rule_filter": lambda rule: True,"model_filter": lambda tag: True,}],"static_url_path": "/flasgger_static","swagger_ui": True,"specs_route": "/apidocs/"
}

flasgger模块的LazyString功能是用来在运行时为某些参数设置默认值。Swagger UI文档的参数，如文档标题、版本、描述等，在info字段中定义。API的基本URL在 "host "字段中指定。Swagger UI的配置细节在swagger_config JSON对象中定义。

最后，使用从flasgger模块导入的Swagger方法来定义swagger对象，如下所示。

swagger = Swagger(app, template=swagger_template,             config=swagger_config)

API函数被定义，Flask应用程序的路由/地址使用@app.route装饰器指定。通过指定YAML文件的路径和GET方法作为参数（参数如POST、PUT、DELETE也可按要求使用），使用@swag_from装饰器调用Swagger UI文档的YAML文件。

@swag_from("hello_world.yml", methods=['GET'])
@app.route("/")
def hello_world():return "Hello World!!!"

注意： 在这种情况下，YAML文件和Python文件应该在同一个目录下。如果不是，YAML文件的正确路径应该在 *@swag_from* *decorator参数中指定。

为了在Swagger UI中实现GET响应，应该在hello_world.yml文件中添加以下几行：

openapi: 3.0.0
tags:- name: Hello World
get:description: None
responses:'200':description: Successful response'400':description: Bad Request'500':description: Internal Server Error

***注意：***如果GET响应没有任何参数需要填写，那么将描述指定为None并在最后定义响应是一个好的做法。

最后，Flask应用程序被运行并在main内部使用以下几行代码执行：

if __name__ == '__main__':app.run()

代码执行时将在开发模式下运行在localhost上，运行127.0.0.1:5000/apidocs时显示以下文件。

正如你所看到的，这个文档包含了YAML文件中定义的API的标题、版本和描述。一旦在Swagger UI文档中选择了GET响应，该文档就会展开为:

当你点击**"试用"按钮时，文件会显示"执行 "**按钮，如下所示。

一旦选择了**"执行 "**选项，"helloworld "的输出就会显示出来，如下所示。

正如所见，API响应被返回到GET方法的 "响应体 "中。响应头 "包含响应的基本信息，如响应的长度、响应的类型、收到响应的日期和时间（时间将按GMT时区显示）等。

创建Swagger UI文档的步骤相关推荐

swagger api文档_带有Swagger的Spring Rest API –创建文档
swagger api文档使REST API易于使用的真正关键是好的文档. 但是,即使您的文档做得很好,您也需要设置公司流程的权利以正确,及时地发布它. 确保利益相关者按时收到是一回事,但是您也要负 ...
swagger api文档_带有Swagger的Spring Rest API –公开文档
swagger api文档创建API文档后,将其提供给涉众很重要. 在理想情况下,此发布的文档将足够灵活以解决任何最后的更改,并且易于分发(就成本以及完成此操作所需的时间而言). 为了使之成为可能, ...
自动生成python接口文档_Django自动生成Swagger接口文档
Django自动生成Swagger接口文档 1. 前言当接口开发完成,紧接着需要编写接口文档.传统的接口文档通常都是使用Word或者一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次 ...
SpringBoot集成knife4j实现Swagger接口文档
前言:如果你是后台开发,提供restful接口给前端,建议你使用Swagger3提供restful的接口文档自动生成和在线接口调试.knife4j是对Swagger进一步封装,其优化了API文档的UI ...
使用VitePress静态网站生成器创建组件库文档网站并部署到GitHub
Vue3+TS+Vite开发组件库并发布到npm 网站在线预览: Vue Amazing UI | Amazing UI Components LibraryAmazing UI 组件库https:/ ...
Spring Gateway聚合Swagger在线文档
Spring Gateway聚合Swagger在线文档为什么需要聚合? 如何聚合? 单个服务如何聚合Swagger? 1.添加依赖 2.基础配置类 3.Swagger文档信息装配类 4.微服务添加引 ...
【愚公系列】2023年02月 WMS智能仓储系统-007.Swagger接口文档的配置
文章目录前言一.Swagger接口文档的配置 1.安装包 2.注入 2.1 Swagger服务的注入 2.2 appsetting.json的配置 2.3 Swagger服务的封装 2.3.1 S ...
sentinel 官方文档_SpringCloud网关聚合Swagger接口文档实践
目前大多数项目都是以微服务架构设计,以前后端分离技术解耦前端开发工程师和后端开发工程师的工作量,这样一来前后端的对接将是一项重要的沟通工作量,如果后端没有一个合适的API文档,那么这样的前后端对接将是 ...
phpexcel 导出循环增加列数_基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (补充篇)...
前言在上一篇导出文档番外篇中,我们已经熟悉了怎样根据json数据导出word的文档,生成接口文档,而在这一篇,将对上一篇进行完善补充,增加多种导出方式,实现更加完善的导出功能. 回顾 1. 获取Sw ...

创建Swagger UI文档的步骤

创建Swagger UI文档的步骤

创建Swagger UI文档的步骤相关推荐

最新文章

热门文章