sdk: client libraries for all languages

[aeneasr]

Apparently, there are ways to do with using swagger/raml, which can be transformed with e.g. https://apitransformer.com/ or directly from API blueprint

[waynerobinson]

Auto-generated libraries is probably a good starting point when there is nothing else. But they usually don't follow the form you'd expect from the language you're using them within.

I don't want to make any promises for myself and @andrewmcnamara but we might be able to release what we're creating for Ruby as open-source. Although not for our first implementation which is a combination of both it being more tightly wound in our existing application and us still getting our heads around the exact implementation details here.

[aeneasr]

That would be awesome, let me know if I can help! :)

Am 12.09.2016 um 07:12 schrieb Wayne Robinson notifications@github.com:

Auto-generated libraries is probably a good starting point when there is nothing else. But they usually don't follow the form you'd expect from the language you're using them within.

I don't want to make any promises for myself and @andrewmcnamara https://github.com/andrewmcnamara but we might be able to release what we're creating for Ruby as open-source. Although not for our first implementation which is a combination of both it being more tightly wound in our existing application and us still getting our heads around the exact implementation details here.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub #249 (comment), or mute the thread https://github.com/notifications/unsubscribe-auth/ADN1eieXBYxtXm2nn-BswzZVG3Mr6fC9ks5qpN9OgaJpZM4J5ptZ.

[amerdidit]

@arekkas do you have any other plans to include swagger in hydra?

[aeneasr]

@amerdidit the api docs are available on apiary, which supports export to swager iirc.

[nikolay-turpitko]

@arekkas as we discussed in the gitter, I've tried to convert API spec from apiary to swagger and generate code from it in my own project (using go-swagger). You may check results here (this is a folder of my project, containing interface to Hydra and unit-test for it). Here is the difference between API invocation without and with swagger-generated code (to highlight "sdk" usage).

update-spec is a script I used to fetch API spec from apiary and convert it to swagger 2.0 yaml with online converter API (you need an account to execute it). After conversion, script applies 3 patches to downloaded yaml file. I intentionally separated this patches to clarify required changes. First of them only fixes spec so it won't fail validation (online or with go-swagger). Next patch adds some missing parts to the spec (oauth2/revoke request and JWK type definition). I haven't found all possible issues in the spec, only those, related to the methods I actually use in my project. Finally, last patch removes all staff I don't use, because some lead to error during code generation and I decided to leave it for now.

Actual generation runs during project build with go:generate. I added generated code to gitignore, after build it would appear in the folders 'client' and 'models'.

Below is a summary of my findings about Hydra API and generation process:

• Some parts of spec, which I don't use in my project, caused errors during model generation. I just removed them from my version of spec, but they stay in the full spec.
• I had to enhance JWK type definition, otherwise generated code failed to unmarshal it.
• I changed some tags and operationId's in my version of spec, otherwise go-swagger generated ugly names for packages, types, fields and methods. But these names may not fit into human-readable documentation well.
• Even with changed names I was not able to fine tune generated names. For example, it changes 'JWK' to '_j_w_k' in package name and 'jwk' to 'Jwk' in property name. Both originate from the same field in yaml.
• Model of the returned errors is, probably, out of sync with actual implementation.
• oauth/revoke request was missed in original spec.
• go-swagger uses pointers more often, then necessary, but it's known issue.

Regarding PR, I just don't know what is worth to pull into Hydra project at the moment. I may give you partially fixed swagger spec (or you may easily create it with my script). But someone should check and fix the rest of the spec.

Regarding this issue as whole, I think, I'd be pretty happy to have actualized swagger spec in the Hydra project, so that I would fetch it into my own project, remove all unnecessary parts from it and generate my own lean API. It would be even better, if Hydra used API versioning and versions wouldn't change between major releases. This way, I'd be able just generate "sdk" for my own use on whatever language I need. I suppose, it can be pretty difficult to test and support all SDKs on all different languages. If you want to do this, it's, probably, worth to move this support into different github projects and leave only spec in the main project.

If you are interested in using go-swagger in your project, you have a couple of options:

• You may want to use it only to generate client SDK. In this case you may create spec manually, or generate it from annotations in your code. Annotations you'll create manually as well, so difference only in that annotations are closer to the code, so you'll sooner notice them when you change the code.
• You may start from spec and generate both client SDK and server-side stubs from spec.

Obviously, you'll need to use some other swagger tool to generate SDKs for other languages.

[aeneasr]

Hey @nikolay-turpitko thank you so much for the sump up and the hard work. The system behind apiary is open source, it's called api blueprint. There are some converters for it that work with command line:

• https://github.com/kminami/apib2swagger
• https://github.com/lucybot/api-spec-converter

Also it looks like apiary will move to OpenAPI spec anyways: https://blog.apiary.io/2016/01/18/We-ve-got-Swagger

By the way, I think we should define the APIs in OpenAPI spec as well (which is swagger iirc)

[aeneasr]

The api blueprint is: https://gist.github.com/arekkas/e5cd5a455d68ba4e5bc0457144125a68

[nikolay-turpitko]

@arekkas I've tried to use both apib2swagger and api-spec-converter. Unfortunately, all 3 of them (if count apimatic online converter, which I used before) produce differently incomplete swagger spec.

apimatic created some noise, but extracted more information and produced more reliable references and definitions.

apib2swagger lacked some of references and definitions. For example, it completely omitted definitions for warden endpoint.

api-spec-converter created output file with all sections in different order. I was not able to work with this output. Probably, it's output is syntactically correct, but I was not sure if the order of sections is stable between invocations, so I was not sure if patch tool would work with it.

[aeneasr]

Damn this sucks. Maybe there is no way around this and I just need to convert this manually. Could also be an idea to improve the API docs.

[nikolay-turpitko]

@arekkas: https://gist.github.com/nikolay-turpitko/472213904f324ef89cb27a9225adb142#file-hydra-yaml

I've merged output of all 3 tools. Process was mostly manual. File validates with go-swagger and online swagger editor. Both online and go-swagger can serve it with swagger UI, seems OK. Go code for client also can be generated from it. I've tried to convert it back to apib with apimatic, but, of course, result is not quite similar to original file. You should check this file, because something may be missing. For example, basic auth headers are lost for sure. They, probably, should be similar to oauth/revoke, which I added manually. I've not tried to compile generated code yet.

Edit: changed link, so it point directly to file, because I added also both script and generated apib there and yaml get lost between them. Also, I've tried to compile generated code, but after some "beautification" - I've changed human readable names in spec to generate less ugly names in the code (don't know how to do it right, probably it should be done right in the swagger spec). It works.

go-swagger uses tags as package names, but swagger UI uses them to display API doc to the user. Also, I changed some type names, generated by converter, probably this part might be done right in spec - someone should review the spec and choose nice names instead of generated. I'll add link to my patch here (just for idea what I'm talking about) when I push it.

Edit 2: You may also use this link to see spec it UI, just submit it with previous link in the field at the top. And here is the patch which highlights fields of yaml files, used by go-swagger to generate code. It uses tags as package names, so I converted them to lowercase and just one word. It uses operationId as name for the methods and names of definitions goes into generated type names.

[aeneasr]

Hey @nikolay-turpitko thanks for everything. I have some things to do, but I'll check over it soon!

[aeneasr]

We now have swagger-based docs!

[aeneasr]

This is now possible using swagger-codegen