Good rest code generation and documentation tool [closed]

Question

I have been considering a documentation tool for building a backend for a web service to be used in multiple clients along with OAuth and possibility of multiple revisions. I already knew about apiary but doing a little research I found other considerably good solutions with lucrative promises.

RAML seems to be promising good code generation and api reusability. But it doesn't seem to be capable of creating a mock server. And I can't understand why apiblueprint can't be used to generate client side libs and server side skeletons for REST API.

The best use case for us will be upon documentation of the api, client iOS/Android/wp/js library for consuming the service can be auto generated along with an node express/restify app which provides skeleton to write code. Along with api tests and load tests.

Which solution out of RAML/Swagger/Apiary fits the best for this?

Ionosphere

I want to write a code generator for angular to work with this but need some support – Mroz

Code gen for javascript is already available, it is used here github.com/mulesoft/api-console/blob/master/bower.json. – Ionosphere

github.com/raml-org/raml-js-parser See at the bottom of Readme.md "in browser usage". – Ionosphere

The api-console is not a light touch. It's nearly a megabyte of code minified. In order to parse a data-structure and convert it to a collapsible list, they felt it would be necessary to cram angular, bootstrap, and jQuery into their vendor.js file and their own code... holy cow. They reinvent the date object at one point and define their own forEach method. Oh and there's a lovely feature where you can let all the RAML dependencies and traits get built on the client-side by having it request more files from the !@#$ing server. What % of Java devs do you suppose will always choose perf murder? – Repudiation

Answer 1

Please check out Swagger Codegen (free, open-source), which can generate both server stubs and API clients in different languages.

Many companies/projects are using it in production: https://github.com/swagger-api/swagger-codegen#companiesprojects-using-swagger-codegen

Supported langauges/frameworks:

API clients: ActionScript, Bash, C# (.net 2.0, 4.0 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign), Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, Python, Ruby, Scala, Swift (2.x, 3.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)

Server stubs: C# (ASP.NET Core, NancyFx), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy), PHP (Lumen, Slim, Silex, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Scala (Finch, Scalatra)

API documentation generators: HTML, Confluence Wiki

Disclaimer: I'm one of the top contributors to the open-source project.

UPDATE: On May 2018, about 50 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen to maintain a community-driven version called OpenAPI Generator. Please refer to the Q&A for more information.

Impalpable

@bummi swagger codegen is part of the Swagger ecosystem. The author did ask about it but no one has provided any details about swagger or swagger-codegen so far. That's why I pointed it out to make it more obvious to others who've the same questions. – Impalpable

Answer 2

Disclaimer: I work for Apiary

I don't think it's a good idea.

Your need for mock server hints at the fact that you've accepted the path of description-before-implementation, which is good.

However, the idea is that once developing against mock server, you iterate on the API design (that is one of the reasons why it makes sense to do it in "text" tools instead of code)...and that is the hard part.

There are some emerging tools that support scaffolding, but the real problem is how to update the scaffolded app after the blueprint has been updated. I know some people are tackling this, but they are not released yet.

In my opinion, the best approach is to develop real prototype against the mocked API to test the UX of the resulting app. Once the design is reasonably stable, you start developing other clients as well as server, eventually extending the original design.

You test them with respective tools found in the respective languages as their are best for given use case. To test that implementation conforms to blueprint (aka written contract), you can use dredd.

Any tool that cooperates on top of that should take blueprint as an input instead of generating the library to extend manually that is impossible to maintain.

Penurious

You are right about the scaffolding issue but seems resolvable upon reaching a good structure and code generator. And it certainly is possible with Java compile time annotations. Would love to find out more! – Ionosphere

The question would be can a mock API Blueprint be used to automatically generate a strongly typed library with proper documentation for iOS and android, so that UX can be tested? Is the information listed in Blue print enough for this? – Ionosphere

Moreover Format 1A of Blueprint API dosent seems to support security anytime soon? – Ionosphere

Yes, there is enough information to generate strongly typed library. No, we are not doing it yet for the reasons I mentioned. – Penurious

As for "security", is this a fancy way for saying "authentication"? This is coming soon with 1B with broader support for reusable patterns. See github.com/apiaryio/api-blueprint/issues/11 with related issues. – Penurious

Seems promising, but went with RAML for now. Thanks for getting back. – Ionosphere

Answer 3

RAML does provide an integrated, free, hosted mocking service that you can deploy with a single button click in the API Designer. Once you've enabled mocking, try-it will be immediately enabled in the integrated API Console, and you can further exercise your mocked API using the baseURI inserted into your RAML file.

In addition, we will be open sourcing additional server frameworks (we already have Mule and JAX-RS frameworks) in the near future (including Node). Client generation is a bit further out, but also coming quite soon (javascript first, then others).

Disclosure: I am heavily involved with the RAML initiative, and work for MuleSoft as a Product Manager for many of the RAML tools we develop.

Pulcheria

I should mention as well that the RAML spec is designed to provide sufficient information to generate strongly typed, well-documented libraries. We also support definition of most of the common security patterns in modern APIs, including custom approaches, through the the Security Schemes pattern in the RAML specification. – Pulcheria

When can quite soon mean for iOS is there any roadmap? – Ionosphere

Answer 4

If the RAML console is not lightweight enough, you might find https://github.com/kevinrenskers/raml2html really useful and easy to start with.

It doesn't contain all the features that the RAML console does (like Try out, for testing the API from there), but is still a great documentation tool.

Roseannaroseanne