Provide an OpenAPI spec for Notify REST API

[jimleroyer]

Description

As a REST API user, I need the Open API spec that described Notify's REST API, so that I can have an extra documentation and easily generate client code from this.

WHY are we building?

REST API users want Open API spec because it's the sort of documentation it is a clear standard in the industry but mostly, it allows to generate client code automatically. Hence this way a user can keep up to date with our spec with any language/tool that supports it.

WHAT are we building?

We'd need to annotate our REST API endpoints visible to our users with their usage and data types. Then users can retrieve this documentation automatically from an URL that would describe these.

VALUE created by our solution

A better UX for our REST API, more documentation and less need to update our client libraries too (because users can basically generate their own client from this spec instead of us having to create one -- but client libraries present major advantage too if we maintain these correctly).

Acceptance Criteria** (Definition of done)

Given a potential REST API user, when the user wants to integrate with Notify through the REST API, then the user generates the client from the OpenAPI spec or consult it with an industry accepted standard.

• [ ] generate for open API and not our closed API
• [ ] machine readable documentation

Additional info

• This was requested by one of our user via this Freshdesk ticket.

[jimleroyer]

This needs to be implemented in order to enable automated security scans by ZAP and the OWASP security suite, as the latter needs the OpenAPI spec to be fed in order to know the endpoints to scan.