OpenAPI 3

[roberth]

Adds OpenAPI 3 schema in parallel to existing Swagger 2 schema, as backend codegen currently relies on that.

• See if it works
  • Figure out Swagger UI
• Check sum type representation
• Manually test the functionality in commit "Add OpenAPI 3 non-trivial instances"

For #553

Retrievable with

nix run .#internal-hercules-gen-swagger -- --openapi3 | jq . >openapi3-draft.json

[Kranzes]

This does not pass the validation on https://editor.swagger.io/

[roberth]

Thanks, I didn't know about that.
Looks like the library put some parentheses in identifiers. It suggests that they can be percent encoded, but it's probably better to drop them altogether, because I don't think other tools will handle parentheses very well.

[Kranzes]

Also theres like a ton of duplicated "jwt" things

[roberth]

I've made two fixes in #590.
It passes the validation on https://editor.swagger.io/ now.

[Kranzes]

It seems like I still need operationId. Could you check if it can be added via the openapi3 library you're using for HCI?

Context for why I need it: oxidecomputer/progenitor#517 (comment)

[roberth]

Could you try #592?:

nix build hercules-ci-agent/openapi3-operationId#hercules-ci-api-openapi3

[Kranzes]

The client creation no longer fails on that (fails on something else now). So I guess it's fine? One thing that looks wrong to me is the way you just use replace many times with hard-coded values. Maybe there's a nicer way of doing it that's more dynamic?

[roberth]

Upstream doesn't support it properly.

• OperationId Combinator haskell-servant/servant#1276

The string replacements are a bit ad hoc, but it's the most efficient way to add this information, until servant implements it properly.
Something more automated would probably lead to worse identfiers.