Improve/extend Documentation

[ISO50]

Decide on what type of documentation do we want to use:

• are we fine with the readme and api doc as is?
• do we want to provide additional diagrams/code examples to also explain OAuth 2.0 to a certain degree to really make it easy for the developer to use this lib

[ISO50]

First thing we could do, is to improve the README introduction. After reading the introduction, the following points should be clear for the audience:

• We have tooling to secure easily your express endpoints
• We have a TokenCache implementation that encapsulate the process of requesting a token and cache it until it's invalid
• If user want to use it's own cache all token related low level functions are available as well
  • The oAuth flow's that we support
• You can use it with Typescript, ES6, ES5 on node and in the browser (at least how to do it with fetch).
• We should provide links that showcases how to use it to:
  • Secure your REACT / Angular / whatever app login
  • Make secure request from your frontend to the backend
  • How to secure your backend services
  • How to make safe request from service to service

So my plan is to have in the readme just an introduction, release history and migration paths.
And put the more detailed stuff to various HOWTO docs.

@bzums @Retro64 what do you think?

[ISO50]

HOW-TOs:

• protect server endpoints with oAuth
• Request Token to communicate with oAuth protected endpoints
  • Use Token Cache .....
• How to build a login with oAuth Authorization Code flow
• Mock Tooling
• Other
  • TBD

[Retro64]

I like the idea, but we should consider providing typedoc additionally

[bzums]

Have a look at https://github.com/zalando/zalando-howto-open-source, specifically https://github.com/zalando/zalando-howto-open-source/blob/master/READMEtemplate.md and https://github.com/noffle/art-of-readme to get some ideas about style and structure of the README/documentation

[Retro64]

@bzums @ISO50 Should we tag it with 2.0.0, as we decided to close the ticket on 2.0.0 release?

[bzums]

During the course of releasing 2.0.0 we tackled some points we wanted to tackle with this ticket. Now the open issue for this ticket would be:

• add code examples and diagrams to explain OAuth 2.0 (to a certain degree) and how it can supported with this lib

[Retro64]

We should think about concrete examples for the different configurations within the API doc