问题
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?
回答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.
回答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.
回答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.
回答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.
来源：https://stackoverflow.com/questions/22534792/good-rest-code-generation-and-documentation-tool