ZMS-154

[NickOvt]

Change old documentation file for the new autogenerated one

[louis-lau]

🎉

It's complete now? If you'd like I can review it in a little bit

[andris9]

🎉

It's complete now? If you'd like I can review it in a little bit

Yes, @NickOvt has been busy with it, and finally, no more yaml wrangling by hand 🥳 All the endpoints are documented as well, even the most obscure ones.

[NickOvt]

@louis-lau If you have time then of course you can review it!
Overall indeed all the endpoints have been converted to be automatic, so changes should be easy and straightforward.
And also the new documentation is up-to-date with the endpoints, so they include latest request params as well as response types.

[louis-lau]

On first look the spec doesn't seem to be a valid openapi spec, lots and lots of errors. I'll take a look.

[louis-lau]

I've opened PR #694 and PR zone-eu/restify-api-generate#15

These should at least fix the spec so it's an openapi spec and there are no errors. There's still various warnings though. Can I leave fixing those to you @NickOvt? You should check the spec on https://editor.swagger.io/, you'll see the warnings in the sidebar. For example, this isn't really valid:

password:
  type: string
  description: New password for the account. Set to boolean false to disable password usage for the master scope, Application Specific Passwords would still be allowed
  enum:
    - false
    - ''

enum value should conform to its schema's type

Even if the type did match, the enum suggests the value here can only be false or '', which of course is not the case.

---

I also think we should set the operationIds manually per endpoint instead of having restify generate them automatically. We should be able to just use the old ones. For HTML docs it doesn't really matter much, but when generating api clients it matters quite a lot. It essentially determines the function name you'll be calling.

For example, with the old spec I'd be calling:

this.messagesApi.updateMessage()

In the new spec that would be:

this.messagesApi.putusersusermailboxesmailboxmessages()

I'm sure you agree that that's not very readable haha

---

I haven't looked at the content of the schemas etc yet, will do that later. Very excited to have this automatic generation!