Improve documentation

[anymaniax]

I did the documentation really quickly. Could be interesting to add more guide or improve some explanation.

[wouterkroes]

@anymaniax I would like to help! What is the next step?

[anymaniax]

@wouterkroes Thanks. First could be interesting to check if everything is well explained or if there is a need of adding some information. After that, I would like to add more guides and more examples

[wouterkroes]

@anymaniax sure thing! How would you receive the feedback if find something not well explained? Where should I put it, here?

[anymaniax]

@wouterkroes Yes we can discuss it here or you directly open a pull request

[wouterkroes]

@anymaniax Okay, I have read all the documentation and in general I think it looks good! 💯

I have created a PR with small tweaks -> https://github.com/anymaniax/orval/pull/181

Besides the PR I have some remarks/questions:

1. CLI Project feature (https://orval.dev/reference/cli)

I could not find an example of how to use the CLI project feature. Maybe add an example orval config where project is used?

2. VSCode extension (https://orval.dev/reference/integration)

To me, it unclear what the VSCode Orval extension does? It is not clearly stated in the VSCode marketplace. Maybe it is a good idea to promote/explain why to use this extension in the docs

3. https://orval.dev/

"Generate, valid, cache and mock in your React and Angular applications all with your OpenAPI specification."

It could also be used for Vue or Svelte. So I would recommend making it more general Something like "Generate, valid, cache, and mock in your frontend applications all with your OpenAPI specification."

[anymaniax]

@wouterkroes awesome job!

• For the first point, it's a good idea.
• For the vscode extension, I need to update the orval version on it first and it's can be used to search for orval config in your opened workspace and run orval without a terminal. Could be a good idea to promote it yes!
• And for the last point, you can add it to your pull request it's a good idea.

Thanks a lot for your help. It's beginning to be difficult to maintain everything me.

[wouterkroes]

@anymaniax No problem, happy to help! 👍

• [ ] I think it is faster if you yourself add CLI project feature example code.
• [x] I added some details about the vscode extension on the docs page.
• [x] I updated the text in the docs from the last point.

Pushed all changes to my PR.

[anymaniax]

Thanks! Can I already merge your pull request?

[wouterkroes]

Yes, the pull request is ready to go

[anymaniax]

Done thanks 🎉

[yekver]

Hi there! I also would like to help a bit :)

For me it was mutator section was unclear.

1. I didn't get what are the properties name and default stands for. I had to look through the source code to get it right. I think that example with two mutators is needed to understand that name stands for exported mutator function name. default prop is still a bit confusing for me because mutator isn't defined as a default export function. And I didn't get why the line with default prop is commented? true is a default value or not?
2. I'd recommend to switch from CJS to es modules in orval.config.js because it's more easy to use and there no import {defineConfig} from 'orval' in provided examples.
3. There three examples of custom-instance.ts and it's quite hard to read and detect the difference them. I think 2 examples will be enough there is no need to provide an extra example for an alias prop.

4. // @ts-ignore
   promise.cancel = () => {
    source.cancel('Query was cancelled by React Query');
   };

   is a legacy approach I'd recommend to update this.

[anymaniax]

Any help is welcome. For point 4, I am currently working on it. But for example, svelte query doesn't have that feature yet so I thought about something to handle that case but it will take a bit of time to implement it

[ristomatti]

While upgrading React Query from v3 to v4, I noticed this method of cancellng requests is either removed or deprecated. I say either or as v4 migration guide says it's been removed while the documentation still instructs to use this syntax for older Axios versions.

https://tanstack.com/query/v4/docs/guides/migrating-to-react-query-4#the-cancel-method-on-promises-is-no-longer-supported https://tanstack.com/query/v4/docs/guides/query-cancellation#using-axios-v0220

[anymaniax]

Hello @ristomatti, normally it's removed in v4 and needs to be updated in the doc too

[ristomatti]

@anymaniax Thanks! I've just been trying to figure out if it is or not. I just figured though we have this configuration on a custom instance even though we're generating only Axios requests :slightly_smiling_face:.

[Samuel-Morgan-Tyghe]

https://orval.dev/reference/configuration/output#mutator custom instance is incorrect here, needs replacing with https://orval.dev/guides/custom-axios

[melloware]

@Samuel-Morgan-Tyghe can you submit a PR fixing or improving the docs?