Create API documentation

[QaysarA]

As a internal VA developer
I want to access API documentation for VANotify
to enable integration with VANotify

In scope:
Documentation for endpoints currently in postman collection including:

Organization:

• create
• update
• get

User:

• create
• update
• get

Service:

• create
• update
• get

Template:

• create
• update
• get one template
• get all templates

API Key:

• create API Key
• revoke API Key
• get one API Key
• get keys

Other:

• send notification

• get notification status

• how JWT is generated
  - we need to make sure there is a way for consumers to interact with the API without knowing the secret

• Sync with team to consider if all endpoints listed above should be shared externally to other VA devs. "Process" chat seems to be needed. -> Discuss this during desk check.

Notes:

• format is Open API
• No automatic updates to documentation
• We have Json Schema definitions for some of the endpoints. Consider using tooling that can convert Json Schema to Open Api

Out of Scope:

• Publishing documentation somewhere where it can be accessed via Open API UI

[sarahproof]

Do we know how we want this documentation to be accessed? Would it be deployed with the app?

[lingtran]

Looking into resources:

• https://pypi.org/project/jsonschema-to-openapi/
• https://github.com/openapi-contrib/json-schema-to-openapi-schema
• https://swagger.io/specification/

[jsmithVA]

Reviewed the users endpoints. Found the following issues:

• for POST create and POST update user, state is listed as a boolean in the response but it is actually a string

• No error conditions are documented for POST create (ex. malformed request) or POST update (ex. user not found)

• The documentation says that e-mail address is only required when auth is set to email_auth, but it is required when it is set to sms_auth as well. Mobile number is only required when set to sms_auth.

• There is no documentation for a GET single user endpoint though it appears to work. It will also need error condition documentation.

• POST update user lists both email and mobile number as not nullable, but mobile number is nullable as long as auth is set to email_auth.

[jsmithVA]

Reviewed the services endpoints. Found the following issues:

• Need error code documentation (example: duplicate service name on POST create and POST update)

• GET all services and POST create service list whitelist as an array with an object of arrays. But it returns as just an array

• GET single service endpoint exists but is not documented

• POST update service shows inbound_url as a url format but the API requires a uuid

[jsmithVA]

Reviewed template endpoints:

• Subject is required when type is email