Add a REST API OpenAPI specification

[schultzp2020]

Which area this feature is related to?

/area api
/area registry

Which functionality do you think we should add?

Why is this needed? Is your feature request related to a problem?

As a developer, it would be easier to update the REST API if we had defined OpenAPI specification that codegens the the index server with the corresponding bindings. This would create a better workflow to understand what each route does. In addition, this would allow for better documentation and automated mock testing.

As a consumer, it would easier to consume the REST API if the documentation was clear and always up-to-date. In addition, this change would allow codegen of nonvendored types between languages Edit: After #1146 is completed.

Describe the solution you'd like

1. Use json-schema-to-openapi-schema to convert the devfile JSON schema to the OpenAPI schema. Covering this in #1146.
2. Create the REST API OpenAPI schema with the devfile OpenAPI schema reference to the Go schema of the devfile specification.
3. Use oapi-codegen to codegen the index server with the corresponding bindings.

For more information on JSON schemas and OpenAPI schema read this.

Describe alternatives you've considered

We could codegen the OpenAPI specification from the source code. However, it is better convention to create the spec and then the source code.

Additional context

blocks #957

Target Date: 07-11-2023

[michael-valdron]

Summary of progress so far: The legacy swagger.yaml file has been replaced with a new OpenAPI v3 spec openapi.yaml which includes all REST API routes and type schemas.

Implementation of OpenAPI code generation has been successful with the use of github.com/deepmap/oapi-codegen, REST route definitions are now generated in endpoint.gen.go and type schemas are generated as structs under types.gen.go. Endpoint handler source bodies are still manually written under endpoint.go however function signatures have been refactored for coupling to the generated definitions (endpoint functions are now receiver functions to a struct that implements the generated interface that contains the definitions for the routes).

Current updates: The endpoints which are not part of the REST API (i.e. the OCI proxy endpoint and registry viewer proxy endpoint) have been defined under the OpenAPI spec, this is because the validator that checks the endpoints against the spec does not allow requests for endpoints not in the spec itself, even if manually defined in the source.

In addition, due to incompatibilities with the JSON schemas (i.e. devfile spec json file), the OpenAPI spec needs to rely on the already generated libraries using the x-go-* fields.

Will provide more updates when I have done more testing with these changes.

[michael-valdron]

The endpoints which are not part of the REST API (i.e. the OCI proxy endpoint and registry viewer proxy endpoint) have been defined under the OpenAPI spec, this is because the validator that checks the endpoints against the spec does not allow requests for endpoints not in the spec itself, even if manually defined in the source.

This change has been reverted due to OpenAPI 3.x spec not supporting proxy route paths. To bypass the OpenAPI validation, the middleware function is only applied to the REST API routes by setting it under GinServerOptions.Middlewares then passing it using the RegisterHandlersWithOptions function rather than RegisterHandlers default function.

[michael-valdron]

1. Use json-schema-to-openapi-schema to convert the devfile JSON schema to the OpenAPI schema.

Created #1146 to cover the OpenAPI conversion of the devfile specification part.

[michael-valdron]

Code generation is now being used during the build process, CI updated to install the dependency for the code generation. An additional workflow step for checking the commited source generated files for changes and prompting the author for an update to the source generation: https://github.com/michael-valdron/devfile-registry-support/blob/4c040e7598521fd440e0f39d80e600888053a42d/.github/workflows/ci.yaml#L45

Additional time provided to the target date for the size of the review process.

[michael-valdron]

Included documentation on OpenAPI source generation for the index server, tied PR devfile/registry-support#175 is ready for review.