Include model samples in the docs?

[shrihari-prakash]

I noticed several issues in the past pertaining to the usage of this library from people who are just starting out with this. I think this primarily comes from the fact that the getting started page consists of everything but a sample of the model. As a new user, I do not want to go through each and every function in the models page and implement it when all I want is to see if the library fits my needs. I rather want a model template that I can copy paste and then build from there.

I know that we have a examples repository that we point to when people ask about the models, but isn't it better to have this on the getting started page? This could improve the adoption of this library by a lot.

[jankapunkt]

Hey @shrihari-prakash good to see you back 👋
I like the idea and I also think we need a general revision of the docs from a beginners perspective.

At the time when I started with OAuth2 I already knew concepts so I had an easier time reading through the docs.

A starter template is good but we should be aware of security so that people who blindly copy paste will run into "not implemented" errors, forcing them to implement their part of the model property.

[jankapunkt]

@shrihari-prakash I reinvited so you can easily help in working on the docs and examples

[shrihari-prakash]

I created an initial PR (#361) as a starting point which we can improve along this discussion.

That was pretty swift!

We should rather focus on real world usecases with proper default examples. Sometimes I am thinking too defensive.

It is actually very good to be pretty defensive because it is very easy for someone to shoot themselves in the foot when implementing auth :) Better to be careful.

Coming from this it might be a useful thing to implement each workflow in a minimal, yet realistic way in the examples repository, then (once they are merged and stable) use their code and add to the "getting started" page in the docs.

I would be okay with both (little bit inclined towards having it on the docs for better readability and sectioning but we can't go wrong with either I guess). Let us collect the examples in the repository and maybe link it to begin with and then move on to the next steps.

I shall add an example for authorization code to the samples repo and raise a PR to begin with if you'd be okay with that.

And thanks for the reinvite, I must have missed the initial notification sorry!

[shrihari-prakash]

Just now looked at the complete code on the examples repo. Yes, I do agree that it's good to have complete and minimal working examples on the repo and point them from the docs :)

[shrihari-prakash]

@jankapunkt if you do agree to creating an auth code example, my proposal would be to create a single node server, where there will be login UI served via express ejs templates. There will be a sample authorize route and some protected routes for testing. Let me know if you'd like me to go ahead or let me know if you have something else in mind!

[jankapunkt]

@shrihari-prakash go for it, i think its a good idea to add client code as example since the library itself is clearly omitting it and a few users already asked for guidance there. I added you to the examples repo, too