Hacker News new | ask | show | jobs
by ewittern 3707 days ago
What do you think about automatic generation of client-code in various languages?

With regards to the bugs, were they a result of the implementation and the specification getting out of sync? Would automatic means for creating / maintaining specs be able to help here?
2 comments
7373737373 3707 days ago
I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs.

In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces/signatures can be generated. API specifications could also be more easily transformed by middleware (e.g. when renaming endpoints, combining APIs) if they were machine generated.

As was described above, only few people are acquainted with service description languages, and deeper changes in their semantics over time or the choice of an alternative would require a manual rewrite. Also, some SDLs seem to impose their own higher level ontologies and name spaces, which is another major obstacle to usage for simple systems.

link
krsyoung 3707 days ago
First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist).

Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information.

I would hate for my devops pipeline to kick-off because somebody fixed a typo in some human focused in-line documentation. I personally don't think it belongs in the code but absolutely agree with the spirit of your comment (if you keep them separate it is more work and they will get out of sync!).

The best luck I have is working within the specification (i.e. Swagger) and avoiding doing things that don't model well. This seems backwards, but for most of the development I've been involved with to date it has served the projects well.

Interested if others have had luck embedding API specs into code.

link
ewittern 3707 days ago
Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially when using dynamic languages (JavaScript, Python). One approach is to use dedicated annotators to relate code with parts of an API spec - but then you have the first problem again...
link
wing328hk 3707 days ago
Re: What do you think about automatic generation of client-code in various languages?

Swagger-Codegen (https://github.com/swagger-api/swagger-codegen) is a pretty mature, free and open-source project for generating API clients (e.g. ObjC, Java, C#, Ruby, Python, etc) and server stubs (e.g. PHP Slim, Java Spring, etc). Please give it a try and let us know your feedback by opening a ticket via https://github.com/swagger-api/swagger-codegen/issues

Disclosure: I'm a top contributor to the project.

link