I’d like to use the openapi-generator Maven plugin to generate our API reference docs. I cannot find thorough documentation for the Openapi Generator. For example, there is no explanation of what the so-called “input Openapi spec file”. Where can I find better documentation? Perhaps there is some manual in the original Codegen site?
Related
Im writing a new set of APIs mostly in golang and traditionally we have been writing the API and generating the swagger specs for it. However, I bumped into swagger codegen recently. I think it is a good way to manage APIs. This also ensures that our Swagger is always updated.
Do you think there are any disadvantages to using codegen to generate APIs? Can someone point me to articles for pros and cons?
I'm getting started with OpenAPI generator and would like to learn the best practices and see a list of companies that are actually using SDK generated by this tool (the reason is I feel like the tooling is a little bit behind for OpenAPI v3 so I'd like to see if anyone has a build an end-to-end pipeline).
So far I've found DataDog and their custom tooling and OneSignal's SDK.
We are using crnk JSON API implementation on the server side (Java). I see the crnk documentation here http://www.crnk.io/documentation/. But, I am not able to find the corresponding Java API Reference documentation. Not sure if there is on available ?
no, so far it is not available. but could be added as PR. release automation is currently in progress and the asciidoc documentation already gets automatically published. Adding JavaDoc next to it would be a minor effort.
I have an API which I need to produce documentation for. I've used the following article to setup the documentation on my API and it's working pretty well.
I'm using the: Microsoft.AspNet.WebApi.HelpPage NuGet package to generate documentation for my WebApi and I've been following this tutorial.
http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages
All is working well and I've got some excellent documentation for my Api Endpoints. Sadly the data objects it's returning have no associated documentation and I'm at a bit of a loss as to how to do this. In the past I've used Sandcastle etc and it's combined the documentation files.
So currently as documented I've uncommented the line:
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
This has allowed documentation for the api assembly to be generated but I can't find a way of referencing additional assemblies.
By I can't find a way of referencing additional assemblies. if you are referring to generating help documentation from models present in other assemblies, then you can take a look at the following response:
How can Xml Documentation for Web Api include documentation from beyond the main project?
I am trying to find a documentation or a tutorial about creating and publishing symfony2 bundles for other developer use.
I tried to look at some source code for some public bundles but it seems it needs more in dept understanding.
Is there any official documentation about this ?
You can find most of the recommendations from the official symfony documentation : http://symfony.com/doc/master/cookbook/bundles/best_practices.html
I also encourage you to read this slides from the famous #stof70 and #lsmith, that exposes the most recent best practices about bundles (composer, travis, knpbundles, etc) : http://friendsofsymfony.github.com/slides/there_is_a_bundle_for_that.html#1
There is no official documentation on this topic. But from my point of view I can tell you, that most important things for you bundle are:
Uniqueness
README
Tests
Avoiding dependencies
Good practice also is to tag stable releases.
By the way, at KnpBundles you can see the number left to the bundle name. It represents respectability of bundle within community. You can check most respectable and the looser ones, compare and analyze them to define points, that make bundles successful.