OpenAPI support

[paul-lysak]

Are you planning to add support of OpenAPI (https://github.com/OAI/OpenAPI-Specification)? Do you need help with this?

[aeons]

There is already support for swagger, the predecessor for OpenAPI. I think updating the swagger dependency and fixing whatever breaks from the update would be enough (that might be a lot of work though).

Feel free to submit a PR :)

[paul-lysak]

I mean OpenAPI 3.0 or more fresh which is indeed based on Swagger but isn't 100% compatible. One of the features I miss is the support of arbitrary query parameters (when you don't know the names of all the possible query parameters at the time of writing the spec). Do you think it's OK to replace current Swagger 2.0 spec generator with OpenAPI 3.0 or they must coexist? I'll try to prepare a PR, probably will take a long time.

[paul-lysak]

Unfortunately, won't be able to work on a PR for this issue as #251 was a show-stopper for us, we're not going to proceed with Rho adoption.

[zarthross]

Since swagger 2 and OpenAPI 3 are incompatible should we provide support for both? OpenAPI3 support is a fairly large change. I switched the jars for swagger-core to 2.0.5 and found at least 130 compile errors...

If we decide to support both, should they be separate jars? Mixed together (which we can do since they choose different artifacts and packages for swagger3)? Should we support generating both Swagger 2 and OpenAPI3 in the same project?

The only file that appears to be effected is org/http4s/rho/swagger/models.scala

[chuwy]

Is there any benefits of having Swagger 2? If no - I'd move along and switch to Open API entirely.

[zarthross]

I need to check, but the platform I use at work may not support openapi 3. I'll verify this week.

[RafalSumislawski]

The system I'm working on used to use OpenAPI 3, but after getting some complaints about it being incompatible with various tools, we decided to make a step back and use Swagger 2. So yes, there are benefits of keeping Swagger 2 support.

A notable example of a tool not supporting OpenAPI 3, but supporting Swagger 2 is Postman. postmanlabs/postman-app-support#3390

[vegansk]

A notable example of a tool not supporting OpenAPI 3, but supporting Swagger 2 is Postman. postmanlabs/postman-app-support#3390

It supports OpenAPI 3 since december 2018: https://blog.postman.com/2018/12/11/postman-supports-openapi-3-0/

[nicobao]

Any plan on supporting OpenAPI V3? I think http4s needs to support both V2 and V3, because:

• openapi-diff is only compatible with OpenAPIv3
• Google Endpoints requires Swagger v2 specs
• OpenAPI v2 will generate duplicated enumerations definitions. This is solved in OpenAPIv3 (see "Reusable Enums") using references. When using openapi-generator to generate frontend with OpenAPIV3 this feature is a must because otherwise you'll have multiple generated Enums per DTO representing the same enum in the backend.

How do you type frontend/backend interaction through REST API with rho & http4s otherwise?

[zarthross]

I would love to be able to support both swagger versions. I haven't had time yet to make the necessary changes, so PRs are welcome, but I would certainly be open to dual support.