Design decisions

[reichhartd]

First of all, thank you very much for the library! I discovered it a few days ago and think it's a great initiative. Especially the support for React Query and the MSW could make our work easier.

Currently, we use the TypeScript Axios generator from OpenAPI Tools in conjunction with React Query. I will create a POC for one of our projects in the coming weeks and will be happy to contribute to this project if needed.

To do this, I'd like to understand a few design decisions that I've noticed mainly by comparing them to our current generator:

1. Enums are generated differently.

   export type ExampleEnum = 'VALUE_1' | 'VALUE_2' | 'VALUE_3';
   
   // eslint-disable-next-line @typescript-eslint/no-redeclare
   export const ExampleEnum = {
       VALUE_1: 'VALUE_1' as ExampleEnum,
       VALUE_2: 'VALUE_2' as ExampleEnum,
       VALUE_3: 'VALUE_3' as ExampleEnum,
   };
   

   What advantage does this type have compared to the "regular" TypeScript enums à la:

   enum ExampleEnum {
       'VALUE_1' = 'VALUE_1',
       'VALUE_2' = 'VALUE_2',
       'VALUE_3' = 'VALUE_3',
   }
   

2. Header parameters

   So far, the authorization method and the header parameters of the API Spec are ignored. However, this should not be a problem for us, as we use the same headers for all requests. Was this a conscious decision to avoid having to pass the header parameters per request?

Does it make sense to document such questions and answers for future developers on the website? I can imagine that more questions will arise during the course of the migration, and so they would be bundled in one place.

Many thanks in advance!

[anymaniax]

Hello @reichhartd, thanks already for your contribution!

The difference of the enum are mostly for the compilation to have a smaller bundle at the end. If you take both of them and put it in the typescript playground you will see the difference. Was a decision at the begin of the project.

For the authorisation header I didn't find a good way to handle it that would work for everyone so I preferred to leave it to the user.
If you have ideas I am still open to solution. Maybe something like a mutator would do the job.

For the documentation, It can be improve for sure so If you also have ideas don't hesitate to do a pull request.