seanevan
commented
4 years ago @javier-hulft, thanks for bringing this to our attention. We will update the documentation accordingly. Apologies for consuming your time due to that phrasing.
Closed javier-hulft closed 2 years ago
seanevan
commented
4 years ago @javier-hulft, thanks for bringing this to our attention. We will update the documentation accordingly. Apologies for consuming your time due to that phrasing.
javier-hulft
commented
4 years ago Oh, no worries.
charliecode
commented
4 years ago @seanevan Another quick suggestion which is inline with @javier-hulft. At the moment Swagger's docs for their code generators are quite confusing and the direction they're taking is sort of a mess to keep up with. One huge reason is the overlap between swagger-codegen v2, v3 and now the openapi-generator which is part of OpenAPITools. Which was a splitting point where the founders felt the project needed to go in a different direction. Add to that the fact that swagger-codegen v3 is supposed to support v2. Yet that doesn't always happen out of the box since they wrote new generators for v3 and switched over to using Handlebars for templating over Mustache.
I understand the benefits to using the OAS spec. You can provide us with your generated specs and we should be able to get nice working clients and server stubs for development. However with the current state of affairs with Swagger docs and the overlap with the OpenAPI docs as well as all the different generators for the OAS which Swagger in one way or another recommends, it would really help to have some suggestions of not just which generator to use but also some links to Swaggers or OpenAPITools docs which can point a developer in the right direction who wants to make a truly functional SDK or even just get a working client. Especially since simply creating a client from your specs via swagger-codegen is not going to actually work out of the box, which is what you would expect from a client. The reason for this being the access token logic and the aws4 signature needing added after the client is generated via swagger-codegen or openapi-generator. Just a suggestion, I know I could have saved myself a ton of time had I had just a few simple links and a little bit better explanation.
seanevan
commented
4 years ago @charliecode Thanks for that feedback. Directionally, we intend to package SDKs for the languages most-used by developers, since you're totally right about some of the API-specific supporting functionality, such as AWS4 Signature or helper code for specific APIs, not aligning well with the codegen process.
We would welcome feedback on that notion of installing SDKs from package management systems, as opposed to code generation. Our goal is ultimately to save developers as much effort as possible so you can get up and running with SP-API quickly, but we also recognize that not every development workflow is the same and that code generation might be preferred by some developers.
Best regards, Sean Evans Manager, Support Engineering
jlevers
commented
4 years ago I would like to second the idea of having SDKs available from package managers. It seems to me that developers with custom use cases could still use Swagger or OpenAPITools, while everyone else could just install a package from Maven or Packagist or wherever.
charliecode
commented
4 years ago @seanevan I agree with @jlevers. For the most part SDKs should suffice for most use cases in the most popular languages. In the event they do not, a client could be generated and turned into a custom SDK. That's what I'm currently doing after having generated a client with the openapi-generator for typescript-node. They have prebuilt in interceptors which work nicely for building out the logic to add the aws4 signature as well as adding whichever logic is necessary for access tokens to be autogenerated and added as well. Hopefully I can find a way to make them work for the exponential backoff / retry logic as well, although that may be trickier since the package the generator is using for the http requests does not support it. I'm considering eventually making my package available as it's a nice way to plugin the more difficult parts of making the requests under the current circumstances.
I do have some suggestions on things which would be nice to have added to a SDK provided by Amazon. Like exponential backoff with the ability to add your own retry logic times. Basically some of the things which Amazon recommended be added as best practices in the MWS API and could easily be added to a SDK for SP-API. As an example, with Node using the "got" npm package for http requests, it already has that retry logic built into it. Also having an SDK which plays nicely with serverless (Lambda, API-Gateway, Kinesis etc) principles would be amazing. Whenever building out an app for sellers a large part of it is going to be distributed and run automatically throughout the day via something like cron jobs, so keeping these things in mind when creating the SDK's could really save developers some real time with the more monotonous things and allow them to focus on business logic.
jlevers
commented
4 years ago Another feature that would be really nice in an Amazon-provided SDK: better defined client class structure. For instance, it would be really nice to have all the main API classes (ReportsApi, FeedsApi, etc) inherit or implement a common class, or have their Builder classes inherit a common class. That way, it would be possible to define classes/functions that work with all API classes -- as it is now, any staticly typed language won't allow that.
Maybe it's possible to tell Swagger to do this somehow, and I'm just not seeing the option.
charliecode
commented
4 years ago @jlevers Have you had a chance to look into generator templates yet? If you're wanting to customize it seems like the place to start. Here is a link to that section of the docs for the openapi-generator. I know there are similar for swagger-codegen as well.
jlevers
commented
4 years ago I hadn't checked that out -- thanks for the link! It looks like a really useful tool.
Hello,
I am trying to use swagger-codegen 3.0.20 to generate an LWA-capable java client. From the root folder of the git checkout I am running:
swagger-codegen generate -l java -i models/finances-api-model/financesV0.json -o java-client -t clients/sellingpartner-api-aa-java/resources/swagger-codegen/templatesErrors out with:
Please either fix or modify the phrase in the docs that reads: "Download the latest version of the Swagger Code Generator" to reflect a valid version range; using version 2.4.13, for instance, runs without issue.