hashicorp / hashicorp/terraform-plugin-codegen-openapi

Consider permitting remote/URL references in `$ref`

Open
#89 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Go
Stars
91
Forks
20
Avg merge
2d 13h
Merged PRs (30d)
1

Description

> Putting this issue out to gauge interest, which we track via 👍🏻's on the issue itself. If this is a use-case that is relevant to you we'd also love to see examples/OpenAPI specs to ensure we end on a good solution.

## Background

Using `$ref` is helpful for splitting OpenAPI spec's into more manageable pieces that can be reused. A good overview of this feature can be found in this document from Swagger: https://swagger.io/docs/specification/using-ref

Currently, `tfplugingen-openapi` supports local references, i.e, where all the references exist in the same OpenAPI spec file. If you attempt to use the generator on a OpenAPI spec that is split into multiple files and contains a remote/URL reference you'll receive an error:

#### OpenAPI spec example
```jsonc
// .. rest of openapi spec
"paths": {
"/pet": {
"post": {
"description": "Add a new pet to the store",
"requestBody": {
"content": {
"application/json": {
"schema": {
// URL reference!
"$ref": "https://petstore3.swagger.io/api/v3/openapi.json#/components/schemas/Pet"
}
},
```

#### Error from `tfplugingen-openapi`
> _time=2023-11-03T08:35:19.696-04:00 level=ERROR msg="error executing command" err="error building OpenAPI 3.x model: remote lookups are not permitted, please set AllowRemoteLookup to true in the configuration\ncomponent 'https://petstore3.swagger.io/api/v3/openapi.json#/components/schemas/Pet' does not exist in the specification\nschema build failed: reference 'https://petstore3.swagger.io/api/v3/openapi.json#/components/schemas/Pet' cannot be found at line 124, col 41"_

## Consideration

The fantastic downstream library we use `pb33f/libopenapi` [does support this](https://pb33f.io/libopenapi/openapi/#documents-with-relative-or-remote-references), we'd just need to consider any potential footguns and accept a potential base URL for resolving remote references from the generator config. URL references _should just work:tm:_, but would benefit from some testing.

```go
// Retrieve from generator config?
baseUrl, _ := url.Parse("https://petstore3.swagger.io/api/v3")
doc, err := libopenapi.NewDocumentWithConfiguration(oasBytes, &datamodel.DocumentConfiguration{
BaseURL: baseUrl,
AllowFileReferences: true,
AllowRemoteReferences: true,
})
if err != nil {
return fmt.Errorf("error parsing OpenAPI spec file: %w", err)
}
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.