Any Tips and Tricks?

[lucadegasperi]

Hi Everyone!

I've recently started using this package to document my APIs and, while the documentation is great at showing what can be done / cannot be done, I have found some difficulties around the best way of documenting my apis. Here are some questions I haven't found an answer yet.

• I'm using passport, how do I authenticate the GET requests this package is making?
• if I'm specifying the @apiResourceCollection and @apiResourceModel attributes why is it not creating the response from a factory I have defined and is using my db to get the first model?
• do you recommend using a separate DB full of fake data to generate the various responses or should I rather be using json response files?
• How do I define different responses based on different parameters passed to the api?
• How do I define different responses based on different access token scopes when using passport?
• How do I mark some parameters as required when another field is empty or missing?

I think this package is great but it lacks something like a video tutorial that explains what the different configuration options and parameters do and why should I choose one way of doing things rather than another.

[shalvah]

I'm using passport, how do I authenticate the GET requests this package is making?

Authentication is currently a tricky issue. The best thing you can do for now is add an "Authorization" header with your token (or query/body parameters) for when the response call is made. Maybe this is something we can tackle in greater detail in v5.

if I'm specifying the @apiResourceCollection and @apiResourceModel attributes why is it not creating the response from a factory I have defined and is using my db to get the first model?

Usually this means that the factory attempt failed. Try running with --verbose to see what the problem was.

do you recommend using a separate DB full of fake data to generate the various responses or should I rather be using json response files?

Whichever is easier for you. It's probably easier to keep a separate database up to date than manually manage response files.

How do I define different responses based on different parameters passed to the api?

Right now, you can't do that. However you can use the each of the @response* tags in conjunction with status codes to indicate different responses, including multiple responses for the same status code. Something like:

@response 400 {"error": "invalid arguments"}
@response 400 {"error": "missing data"}

We can probably add some feature to improve this going forward. Maybe something like @response <400, missing value> {"error": "missing value"}

How do I define different responses based on different access token scopes when using passport?

...
Maybe custom logic or a middleware? Also remember that there is a plugin system, so you can write a plugin that modifies or sets responses.

How do I mark some parameters as required when another field is empty or missing?

You add it in the description of that field.

I think this package is great but it lacks something like a video tutorial that explains

Probably, but that's an opporutnity that someone else can pick up. I'm not into creating video tutorials. Anyone in the community can do that.

The documentation is pretty comprehensive (I hope), and if you see something that isn't clear, you're welcome to send in a PR. In the future, we're looking to make the docs more guide-y, not just reference materials, so you can also point out any places you think are lacking..

[shalvah]

Hi @lucadegasperi I'm closing this issue since I don't have the permissions to transfer to another repository. Scribe has been released now, so you shuoold open this issue in that repo if you still think it's relevant.

In the meantime, the docs for Scribe have been revamped to make things clearer, and we'll also be releasing some more helpful material in the near future.