Generate OpenApi definition

[tobdru]

We had some issues at the contract between the mail service and our backend. So to integrate the mailing endpoint seamless I had the idea to generate an openapi.json / swagger.json.

This should then contain the different mails as different options for the sendMail & generateMail endpoints.

e.g.:

paths:
  /sendMail:
    post:
      operationId: sendMail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Mail1'
                - $ref: '#/components/schemas/Mail2'

We could then easily autogenerate clients and reduce contract issues.

To solve it I have the idea to generate the general open api spec via: https://www.npmjs.com/package/next-swagger-doc And then manually add the content options.

What do you think about it?

If you have any other idea, I would love to hear it.

[tobdru]

I now had a deeper look into it, and I think a solution could be:

1. adding js doc swagger descriptions to the endpoints
2. adding a 'mailing swagger-generate' command
3. in the command first get the properties of the different mails and add them as types
4. generate the swagger.json

My plan is to do a pr in the next days so I would be very interested in your opinion @psugihara before putting to much effort into it.

[psugihara]

Hey @tobdru, interesting idea. Thanks for tagging me, I missed the earlier issue.

That sounds like a nice way of getting a more typesafe contract and I'll be happy to review and merge.

[tobdru]

After investigating a few more hours, I sadly could not find an easy solution. We were not able find a package to automatically resolve TS types to swagger definition. Therefore I close this Issue.

[psugihara]

ok, thanks for taking a look @tobdru