I've read a lot of StackOverflow questions, but there is no good solution for me. I'm searching for a way to document our API with a version number.
We have v1 and v2. So the best way is to generate 2 different swaggers.
The controllers are in different packages and for one version is one controller.
Is this possible with swagger? And how we can do it?
The best way to do this is to use swagger groups. Check out this documentation: Springfox Documentation
Related
The API documentation created using OpenAPI is usually called using the endpoints /openapi (YAML) or /openapi/ui (Frontend).
How can I rename these endpoints for that I can call e.g. /myappapi and /myappapi/ui respectively? (OpenAPI 3)
This massively depends on how you're generating that OpenAPI. From your comment I see that you're using Eclipse MicroProfile and I've not come across that before, but a quick DuckDuckGo shows this extension might be what you're up to: https://github.com/eclipse/microprofile-open-api
I couldn't see any specific config options to change the endpoint, but you could always slap a nginx redirect in there.
If you're finding limitations with the way you're generating OpenAPI to be a problem, I recommend not doing that.
Of all the approaches: Annotations, DSL, writing YAML by hand in text-editors, or GUI's, I can't help but recommend the GUI approach as it allows for API Design First for new APIs and new functionality in old APIs.
I just did a huge talk about that: https://www.youtube.com/watch?v=nfkppuQ-Eg0&feature=youtu.be
Blog version: https://stoplight.io/blog/api-design-first-vs-code-first/
Otherwise, see if you can pick that extension apart and tweak the config options until it does whatever you want. :)
I would like to use the externalValue of OpenAPI like it's shown in the docs. But it looks like the swagger-UI is currently does not support externalValue (link). Was it ever supported by the Swagger-UI? If so, is it possible to go to some previous version and use it? I have tried to go throughout the release notes and find if it was ever released but could not find it. If it's not supported by Swagger-UI, then why it's described in details in the docs? I'm a bit confused how the OpenAPI/Swagger system works.
If there is no previous version of Swagger-UI which I can use for externalValue, what would be the best option to the current situation? it's a bit difficult to create the examples manually (too big).
Just been researching about this approach and never seem to find a concrete answer online.
I'm seriously curious about the chances of only consuming the API for activeadmin. Then using the JSON objects in React or Angular with a custom UI.
Is this doable?
Absolutely! See https://blog.heroku.com/a-rock-solid-modern-web-stack
For notes on ActiveAdmin vs Rails Admin and other alternatives see https://github.com/activeadmin/activeadmin/wiki/Alternatives
I've also used both Grape and GraphQL in different places, one for performance, the other for flexibility, both reasonable choices.
In theory it is possible since you would just be using the endpoints provided but I think it would be far a far better design choice to choose another API framework gem like grape. One of my complaints with ActiveAdmin has always been that it is not very flexible and you can quickly run into limitations which means that you can't add features that you want to. IMHO you would be digging a pit instead of opening possibilities.
Personally I really like GraphQL (which would be another option) and the graphql-ruby gem is easy to set up and start making highly reusable components that can be leveraged from anywhere admin or frontend.
Can somebody please explain me what exactly is API versioning and why is it needed. I know how to create versions for api on a rails web app, but I really want to know why is it needed. Before somebody downvotes or flags or anything, I googled , I couldn't find any satisfying answer. I would really appreciate it if somebody answers this.
API versioning allows you to have multiple versions of your API and use them at the same time. With this solution, you are assuring backward compatibility for all of the applications integrated with your API.
Simple example
Your API is used by 10 different applications. You are using Basic access authentication, but you noticed that it could be done better. So, you decided to use modify this and use Oauth.
No API versioning
You will have to wait for all of 10 applications to implement changes before releasing the new API version. Otherwise, you will lose the integration. Of course, you can use if/else statements in your code to distinguish which authentication method should you use but this will be not elegant.
API versioning
You can release new API version whenever you want. Then, you can inform your client, that the old API will be deprecated in 3 months, so they have time to implement changes on their side.
Also, you can ask them to add a param to all requests (to choose which API version they will use), and you can set it by the default to the new version. That will allow you to avoid problems with new applications that want to use your API.
Summary(in my opinion):
Pros
1. clean and elegant code (without additional if/else statements)
2. backward compatibility
Cons
1. sometimes you have to duplicate your code
2. it might look like a complex solution at the beginning but don't be scared
Here you can read about two options of API versioning - URL param and HTTP header
I hope that my explanation is clear and helps you understand API versioning
The main reason for versioning your APIs is to provide a constant structure for everybody using them. Let's say you define an initial API for your service (v1) that you send out to your clients. After some time your app changes, and you maybe want to exclude some fields/add new ones. This would be a problem for the client, since their implementation of your API might break if some fields that they are expecting is missing. So you create a v2 with those features, without breaking the initial functionality.
Is there a library that provides a markup for writing REST API documentation? I have seen several companies use similar documentation pattern, e.g:
http://api.teamlab.com/2.0/
http://www.fullcontact.com/docs/?category=person
I am wondering if they are using the same library or service. Essentially, the library should generate pages for API navigation, search and display ( much like YARD for ruby documentation) based on the markup text.
This is what I have found so far:
rapi_doc gem. Here is an article discussing the usage.
You should definitely have a look at Swagger.
It is Open Source, used by hundreds of APIs and also used by 3scale in its API Management solution under the name Active Docs.
Check out IO/Docs from Mashery.
Mashery I/O Docs, the next generation of API documentation and exploration, let developers execute live API calls directly from your docs. Think docs meet testing and debugging, all in one convenient, interactive interface.
Check out the Parse API Docs for another example of great docs.
Also, we spent a lot of time designing the FullContact API Docs. We make use of the Apigee Live API Console as well.
This is a useful gem for api documentaion (Rails4 and Rails5)
ApiDoco https://rubygems.org/gems/apidoco/versions/1.2.0.
It is very easy to setup and have a good user experience.