Open-generator-cli problems, or Swagger/OpenApi recommendations

[mattiasw]

@eriktimmers Nice!!!

[eriktimmers]

@mattiasw how is it working for you now?

I found quite a major bug when dealing with requests that return nothing. I fixed it in this PR.

Also wanted to let you know the new Elm generator is now part of the SNAPSHOT releases.

[mattiasw]

Everything is working fine. All my calls return a value, so didn’t notice the bug. Regenerated and diffed, and no changes on the generated code except you new header.

[eriktimmers]

Thanks, that’s good to hear!

[lazurski]

We are thinking about the following. The app is deployed quite often and sometimes the API definition and generated API changes. Some users have the client open in a tab for long time and sometimes the session overlaps the deployment. In such case our users are getting errors.

I’d like to get any thoughts about this. Below are my early thoughts about it.

What we are considering now is to store a hash of the openapi.yaml file in app’s model (maybe baked in JS code and passed through flags). The same hash should be attached to every API response (I think headers are appropriate for this). If the hash in the response doesn’t match the one in the model, we would pass an error to the Msg constructor and update would reload the page.

• Do you (community) think it’s a good approach?

• Should versioning of the API be somehow supported by Elm OpenAPI Generator?

  I don’t have any concrete idea how it should work. My intention is to start a discussion about a concept and see if we can work something out.

[eriktimmers]

@lazurski what you could typically do is have a versioned base path, like https://example.com/api/1.0.0/. All your endpoints are prefixed with that value. See also the OpenAPI docs.

Instead of hashing the yaml, OpenAPI already supports versioning the specification. (Although with hashing you have the guarentee it gets updated).

Your spec could look like this:

openapi: '3.0'

info:
  version: 1.0.0
  title: ExampleApi
  description: Example API

servers:
  - url: https://example.com/api/1.0.0

...

Or, like you suggested, you could add a header to each request with the right version. Back-end wise it might be easier to deploy different versions under different paths though.

The OpenAPI Elm Generator could also expose the info.version value which would allow you to add a path parameter to each path. Whether you prefer this or updating the base path directly is up to you. Both could be stored in the model.

Example of using a path parameter

openapi: '3.0'

info:
  version: 1.0.0
  title: ExampleApi
  description: Example API

servers:
  - url: https://example.com/api

paths:
  /{apiVersion}/persons:
    get:
      summary: Get all persons
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      ...

components:
  parameters:
    ApiVersion:
      name: apiVersion
      in: path
      description: API version
      required: true
      schema:
        type: string
        format: uuid

So I think OpenAPI already has several options on how to handle this. But it mostly is also depending on how you’d like to deploy the different back-ends. If some small tweaks like exposing the info.version is needed we can update the generator. However, I do not think an out of the box versioning needs to be part of that generator.