Spend hours writing the client, testing, and reviewing the code feels very wrong to me. To make things worst, the tests aren't good enough because there are no integration or contract tests. The client tests will still pass even if the API's URL is changed.
How ca we be more efficient?
I have some ideas but I don't know what's the best.
1. Be more efficient in writing the client
Our client code is written using a low-level HTTP library so just switching to a REST client library such as Square's Retrofit or Flurl will make us more efficient. We still need to write integration or contract tests (see Pactflow) though.
2. Use OpenAPI
OpenAPI is the WSDL of the REST world. The great thing about OpenAPI is it has tools that automatically generates client code. However, those generators are either buggy or may require us to customize the generator.
3. Use Postman or Apimatic
Those two products can automatically generate client code as well but instead of OpenAPI, you use their product to define the API specification. I don't have experience in using those products but my hunch is we will eventually want to customize the generator as well.
What's the best practice?
Do you prefer a hand-rolled client or generated client?
If you are hand-rolling your client, how do you test it?
Lastly, how important is contract testing in your product? It seems that I don't need contract testing to test the schema if I'm already using OpenAPI. Contract testing is still important though for replying the requests or responses.
You can use customized templates (e.g. via -t option in the CLI) to meet your unique requirements. Another tips is to use code formatter such as https://prettier.io/, eslint etc to format the auto-generated code based on the style you want.
Please open an issue via http://github.com/OpenAPITools/openapi-generator/issues/new if you need help with OpenAPI Generator.
Disclosure: I'm the top contributor to OpenAPI Generator
> Spend hours writing the client, testing, and reviewing the code feels very wrong to me. To make things worst, the tests aren't good enough because there are no integration or contract tests. The client tests will still pass even if the API's URL is changed.
There you got your answer: write a tiny wrapper/library that gives you a generic way to write the client. It's not rocket science exactly (so no need to add yet another framework). As for the tests, well, just add tests that you find meaningful.
> It seems that I don't need contract testing to test the schema if I'm already using OpenAPI
How's OpenAPI prevent you from writing tests? Unless you auto-generate the client code (but that's another bad choice imo).
OpenAPI is the way to go. The official client generator libraries are fairly consistent in my experience, albeit the design patterns sometimes stray outside ecosystem standards.
Alternatively, you could add JSON-Schema validation & schema endpoints to the API’s, then use a library like QuickType to generate types. Or even setup sample requests for each endpoint then use QuickType to generate types based on the response JSON.
There are several auto-rest implementations that can generate stuff based on open API specification.