chore: update api specification for vcf-5.2

[spacegospod]

In order to have a good experience with our community, we recommend that you read the contributing guidelines for making a pull request.

Summary of Pull Request

This change updates the OpenAPI document with the one released with VCF 5.2 and regenerates the bindings using a new tool.

Guide for Reviewers

This PR contains two commits to ease reviewing.

0138b31 - Adds a dependency to oapi-codegen, updates the main.go file, updates the README.md, adds the new generated code.

ed2eff1 - deletes all files related to go-swagger and its usage, and all bindings generated with that tool.

FAQ

• [Q] Why are you replacing go-swagger with something else?

• [A] go-swagger supports "swagger" a.k.a OpenAPI 2.0. As of 5.2 VCF's API is released following the OpenAPI 3.0.1 specification. The go-swagger maintainers have stated that they will not attempt to support OpenAPI 3.X in future releases.

• [Q] How did you choose oapi-codegen as the new tool?

• [A] I can answer this question in great detail offline. I evaluated 3 of the most popular tools for generating (Go) code.
  I took into consideration the level of support by maintainers, the ease of adoption, the cost of use. I believe that the tool I chose offers the best trade-off.

• [Q] How is the code generated with the new tool different?

• [A] There are fundamental differences that I will outline in the next section.

• [Q] How did you test this change?

• [A] I created a local override for the SDK and prepared the necessary code changes to the VCF Terraform provider in advance. I ran at least one acceptance test for each and every resource and data source. The changes are available in this branch.

Differences in the Generated Code

The code generated with oapi-codegen is very different than the one we've seen from go-swagger.
In this section I will highlight the most important changes to the bindings and the way the are used.

• oapi-codegen handles optional fields in models properly
  In my opinion there was a fundamental flaw in the way go-swagger treated optional and required properties. In fact I think it had the two concepts reversed.
  oapi-codegen produces struct types for required fields. Optional fields are generated as pointers to structs and can be set to nil and effectively ignored. This should mean that we can finally put an end to bugs like this

• oapi-codegen generates all operations and models in a single file

• oapi-codegen does not generate *Params structs
  We no longer need to instantiate "params" structs when calling APIs with parameters. Parameters are now... parameters to the respective methods.

• oapi-codegen serializes the response based on the status code

Lets examine a fictional GET operation called "CustomOperation". It has a 3 possible status codes - 200, 400 and 500.

The tool produces a method to call that operation "CustomOperationWithResponse" that returns "OperationResult" and error. "OperationResult" is the generated response type and error is the built-it error type.

The error will be set only if there is a non-API-related problem such as a network failure. The actual API errors are part of the "OperationResult" type.
"OperationResult" will contain 3 (among others not of interest right now) fields - JSON200, JSON400 and JSON500.
JSON200 would be of type "OperationResult" while JSON400 and JSON500 would be of type "Error", a generated type, common for all VCF APIs. This allows us to easily read what we need based on the status code (available in a StatusCode field) but it means that we would have to handle multiple error cases every time.
There is an easy solution to this - since all errors are of the same type we can just check the status code and if it is not a "success code" we can just deserialize the body into a VCF error and voila! This is demonstrated in https://github.com/vmware/terraform-provider-vcf/compare/chore/openapi-3-alt and is a lot simpler than it sounds.

Type of Pull Request

• This is a bug fix.
• This is an enhancement or feature.
• This is a code style/formatting update.
• This is a documentation update.
• This is a refactoring update.
• This is a chore update
• This is something else.
  Please describe:

Related to Existing Issues

Issue Number: N/A

Test and Documentation Coverage

For bug fixes or features:

Ran the acceptance tests for the VCF provider.
The corresponding changes are available in https://github.com/vmware/terraform-provider-vcf/compare/chore/openapi-3-alt

• Tests have been completed.
• Documentation has been added/updated.

Breaking Changes?

The bindings for 5.1.1 are being deleted

• Yes, there are breaking changes.
• No, there are no breaking changes.

[tenthirtyam]

LGTM and seems quite clean.

I added 249cc77 to ensure that a updated copyright (Broadcom) is added to the SDK during the go generate.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.