Usage and dependency documentation

[djensen47]

Thanks for the great project! I just wanted to suggest adding some details to the documentation regarding usage as well as dependencies.

It's true that all of these things are available in the code via tests but it's not super intuitive where to find them. As I write this I know that I found the usage; it's fairly easy but since I didn't commit it to memory I'll have to dig through the tests again.

The same is true for the dependencies for Retrofit and Moshi and whatever else I might need. I'll have to dig around in the code to find out what version is supported.

To solve this, it would be great to have something in the README that has the 3-4 lines of code needed to use the generated output as well as the list of dependencies that need to be added to the build.

Thanks!

[cortinico]

Thanks for the great project! I just wanted to suggest adding some details to the documentation regarding usage as well as dependencies.

Thanks for the feedback! Really appreciated.

Have you checked the Examples section of the README? https://github.com/Yelp/swagger-gradle-codegen#examples

It's true that all of these things are available in the code via tests but it's not super intuitive where to find them. As I write this I know that I found the usage; it's fairly easy but since I didn't commit it to memory I'll have to dig through the tests again.

Can you elaborate a bit more on what you haven't found at the first glance?

The same is true for the dependencies for Retrofit and Moshi and whatever else I might need.

Agree that those are hard to find. The idea is again that users should open one of the sample and copy them from the gradle file.

I was discussing with @macisamuele about changing the Examples section of the README and have a table (with every supported/required library as columns). That could maybe be helpful.

[djensen47]

Well yes but it's not super intuitive to go here to find example usage. Again, I eventually found it but the second time I just searched "Retrofit.Builder()"

There's not many files but this was the last one I clicked on swagger-gradle-codegen/samples/kotlin-coroutines/src/test/java/com/yelp/codegen/samples/kotlincoroutines/tools/MockServerApiRule.kt

I'm generally not a fan of "throwing it over the fence" to the tests for basic usage. For OSS libs, the pattern that I personally found to work well is the basic usage followed by detailed usage in code or docs. Basically a "Getting Started" section

---

All I was looking for something as simple as the following on the README. If agreeable, I can do a PR.

---

Basic Usage

val retrofit: Retrofit = Retrofit.Builder()
        .baseUrl(baseUrl)
        .addConverterFactory(GeneratedCodeConverters.converterFactory())
        .build()

val defaultAPI = retrofit.create(DefaultApi::class.java)

Dependencies

< copy & paste deps from sample gradle file here >

or

< links directly to gradle file from readme >

[cortinico]

If agreeable, I can do a PR.

Please go ahead.

I think it definitely makes sense to add this inside the README. We just need to specify that this is specific to a specific configuration (e.g. kotlin vs kotlin-coroutines or similar) to do not confuse readers.