dlt-init-openapi - 为dlt Python库的OpenAPI源生成器

dlt-init-openapi使用dlt rest_api 已验证源从OpenAPI 3.x规范生成dlt数据管道，以从任何REST API提取数据。如果您不熟悉dlt或我们的已验证源，请阅读

• 入门以了解dlt基础知识。
• dlt rest_api以了解我们的rest_api源的工作原理。
• 我们还有一个展示此生成器的Google Colab示例。

特点

dlt-init-openapi可以从OpenAPI规范生成代码，您可以使用这些代码从rest_api提取数据到任何destination（例如Postgres、BigQuery、Redshift...）中，这些destination都是dlt支持的。此外，dlt-init-openapi还会执行一系列启发式算法来发现OpenAPI规范中未明确定义的信息。

功能包括

• 每个端点的分页发现
• 每个实体的主键发现
• 将端点关系映射到dlt transformers（例如，/users/ -> /user/{id}）
• 返回JSON中嵌套结果的JSON路径数据选择器发现
• 认证发现

支持

如果您需要此工具或dlt的支持，请加入我们的Slack社区，并在技术帮助频道寻求帮助。我们通常都会在这里帮助您或讨论功能：）

一个快速示例

您需要安装Python 3.9或更高版本，以及pip。您可以使用pip install dlt-init-openapi命令安装最新版本。

我们将在我们的repo中从PokeAPI规范创建一个简单的示例管道。如果您愿意，也可以指向任何其他的OpenAPI规范。

# 1.a. Run the generator with a URL:
$ dlt-init-openapi pokemon --url https://raw.githubusercontent.com/dlt-hub/dlt-init-openapi/devel/tests/cases/e2e_specs/pokeapi.yml --global-limit 2

# 1.b. If you have a local file, you can use the --path flag:
$ dlt-init-openapi pokemon --path ./my_specs/pokeapi.yml

# 2. You can now pick both of the endpoints from the popup.

# 3. After selecting your Pokemon endpoints and hitting Enter, 
#    your pipeline will be rendered.

# 4. If you have any kind of authentication on your pipeline (this example does not), 
#    open the `.dlt/secrets.toml` and provide the credentials. You can find further 
#    settings in the `.dlt/config.toml`.

# 5. Go to the created pipeline folder and run your pipeline.
$ cd pokemon-pipeline
$ PROGRESS=enlighten python pipeline.py # we use enlighten for a nice progress bar :)

# 6. Print the pipeline info to the console to see what got loaded.
$ dlt pipeline pokemon_pipeline info

# 7. You can now also install Streamlit to see a preview of the data; you should 
#    have loaded 40 Pokemons and their details.
$ pip install pandas streamlit
$ dlt pipeline pokemon_pipeline show

# 8. You can go to our docs at https://dlthub.com/docs to learn how to modify 
#    the generated pipeline to load to many destinations, place schema contracts 
#    on your pipeline, and many other things.

# NOTE: We used the `--global-limit 2` CLI flag to limit the requests to the PokeAPI 
#       for this example. This way, the Pokemon collection endpoint only gets queried 
#       twice, resulting in 2 x 20 Pokemon details being rendered.

将创建什么？

当您运行上面的init命令时，将生成以下文件

pokemon_pipeline/
├── .dlt/
│   ├── config.toml     # dlt config, learn more at dlthub.com/docs
│   └── secrets.toml    # your secrets, only needed for APIs with auth
├── pokemon/
│   └── __init__.py     # your rest_api dictionary, learn more below
├── rest_api/
│   └── ...             # rest_api copied from our verified sources repo
├── .gitignore
├── pokemon_pipeline.py # your pipeline file that you can execute
├── README.md           # a list of your endpoints with some additional info
└── requirements.txt    # the pip requirements for your pipeline

如果您重新生成您的管道，如果此文件夹已存在，您将被提示继续。如果选择是，所有生成的文件将被覆盖。您可能在此文件夹中创建的所有其他文件将保持不变。

仔细查看您的pokemon/init.py中的rest_api字典

此文件包含用于dlt rest_api源配置的字典，这是此生成器的主要输出结果。在我们的PokeAPI示例中，我们使用了一个开箱即用的OpenAPI 3规范。此字典的结果取决于您使用的规范的质量，您查询的API是否实际遵循此规范，以及我们的启发式算法是否能找到正确的值。您可以编辑此文件以相应地调整dlt rest_api的行为。请阅读我们的dlt rest_api文档以了解如何进行此操作，并尝试我们的详细Google Colab示例。

生成的字典将类似于以下内容

{
    "client": {
        "base_url": base_url,
        # -> the detected common paginator
        "paginator": {
            ...
        },
    },
    # -> your two endpoints
    "resources": [
        {
            # -> A primary key could not be inferred from
            # the spec; usual suspects such as id, pokemon_id, etc.
            # are not defined. You can add one if you know.
            "name": "pokemon_list",
            "table_name": "pokemon",
            "endpoint": {
                # -> the results seem to be nested in { results: [...] }
                "data_selector": "results",
                "path": "/api/v2/pokemon/",
            },
        },
        {
            "name": "pokemon_read",
            "table_name": "pokemon",
            # -> A primary key *name* is assumed, as it is found in the 
            # url.
            "primary_key": "name",
            "write_disposition": "merge",
            "endpoint": {
                "data_selector": "$",
                "path": "/api/v2/pokemon/{name}/",
                "params": {
                    # -> your detected transformer settings
                    # this is a child endpoint of the pokemon_list
                    "name": {
                        "type": "resolve",
                        "resource": "pokemon_list",
                        "field": "name",
                    },
                },
            },
        },
    ],
}

CLI命令

$ dlt-init-openapi <source_name> [OPTIONS]
# example:
$ dlt-init-openapi pokemon --path ./path/to/my_spec.yml --no-interactive --output-path ./my_pipeline

选项:

唯一必需的选项是提供规范路径或URL

• --url URL：从OpenAPI JSON或YAML文件读取的URL。
• --path PATH：从本地读取OpenAPI JSON或YAML文件的路径。
• --output-path PATH：渲染输出的路径。
• --config PATH：要使用的配置文件路径（见下文）。
• --no-interactive：跳过端点选择并渲染OpenAPI规范的路径。
• --log-level：设置stdout输出的日志级别，默认为20（INFO）。
• --global-limit：设置生成源的全局限制。
• --update-rest-api-source：更新本地缓存的rest_api验证源。
• --allow-openapi-2：允许使用OpenAPI v2规范。虽然迁移到3.0可以提供更好的结果，但仍然建议使用。

--version：显示生成器的安装版本并退出。

• --help：显示此消息并退出。
• --help：显示此消息并退出。

配置选项

您可以使用--config PATH参数传递一个配置文件的路径。要查看可用的配置值，请访问https://github.com/dlt-hub/dlt-init-openapi/blob/devel/dlt_init_openapi/config.py，并阅读Config类下每个字段的信息。

配置文件可以以JSON或YAML字典的形式提供。例如，要更改包名，您可以创建一个YAML文件

# config.yml
package_name: "other_package_name"

并用它作为配置参数

$ dlt-init-openapi pokemon --url ... --config config.yml

遥测

我们跟踪您使用此工具的方式，类似于我们跟踪dlt核心库中的其他命令。有关更多信息以及如何禁用它，请参阅https://dlthub.com/docs/reference/telemetry。

前期工作

本项目最初是openapi-python-client的一个分支。几乎所有部分都经过了大量更改或完全替换，但仍有一些代码行仍然存在，我们乐于承认我们从原始项目中获得了许多好的想法 :)。

实现说明

• OAuth身份验证目前没有原生支持。您可以提供自己的。
• 生成器不支持端点身份验证。只有全局设置的第一个securityScheme将应用。如果您需要，可以添加自己的端点身份验证。
• 已实现Basic OpenAPI 2.0支持。我们建议在使用dlt-init-openapi之前，在https://editor.swagger.io更新您的规范。