From this question I have seen that
Swagger and Slate serve two different purposes. Swagger is an attempt at a standardized way of describing a RESTful API.
Slate, on the other hand is a pretty theme for writing nice API docs.
It further states that
The two are not mutually exclusive
Ideally, one should generate your slate documentation from your Swagger API description
I am a bit confused. Why would I need slate when I already have Swagger UI like so.
What more do I need to ‘document’ ? I am genuinely asking because as I said I am a bit confused by their uses.
There are a few things that are worth mentioning when creating documentation for a new API.
Swagger provides a really nice graphical interface for exploring the endpoints of an API, but there are still other things that should be included in your documentation, including (but not limited to):
Authentication methods (OAuth/JWT, Basic Auth, Cookie/Session, Apikey/token)
Date formats for date output + timezone
Filtering/pagination/selecting/sorting settings for the API
Which environments exists (usually test, pre-production and production) including their differences.
Error handling including error codes, exception types and logging
Potential rate limits for your API
Terms and conditions for using your API
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've come across two scenarios with regards to creating a REST API in Rails and I wonder which one is preferred. Usually
if you know that you're required to have a REST API for your application at start. Does it make sense to have it in a namespace and thereby duplicating the controller logic?
I've seen examples where people have an application already and later figure they need to extend and offer a REST API. The approach to this has been to create new routes with namespacein routes.rb and controllers/api/whatever.... This still yields duplicate code though, but might be more sensible approach. The difference being a stateless machine for the REST API calls.
Can anyone elaborate on the preferred approach, thanks.
If you create a Rails application, and following the usual conventions, you basically end up with a REST API. Unless you are talking about a more specific meaning of the term (which I am not aware of), "REST API" is more a bunch of general characteristics of the API (i.e., things like statelessness, resource-based URIs if using HTTP, etc.).
So to turn the question right back to you: which case are you thinking about where a (conventional) Rails application is not by extension trivially a REST API?
I have installed jclouds and I am trying to learn how it works internally.
I read all the documentation on the site and on the github but still I have lot of questions about the architecture and implementation of the jClouds.
Do you know where I can find documentation about the deep technical implementation of the framework? I am also looking information on how to add a new provider( for blobstore service)
Currently I am looking into the code but it s not always straightforward what the code does.
The best thing to do is send an email to our dev list. You can subscribe by emailing jclouds-dev-subscribe#apache.org. You can also find us on IRC at #jclouds on freenode.
Adding a new provider is quite an important change for jclouds. The first thing you'll want to do is review How To Contribute. We need to make sure it will work properly and we'll be able to properly test it so don't be discouraged by the reviews.
Having said this, a number of general considerations to take into account when starting a new provider:
New providers are added in labs first, until they are stable.
To follow the jclouds style, use a 3 space indent and a 120 character line length.
We use Guava as our core library. Try to use its utilities before adding new dependencies. In general, do not add dependencies before consulting our dev# list.
We require both live and mock tests. "mock" tests verify that the api generates the expected request according to the method annotations, and that the response is properly parsed. We use MockWebServer to do that, and you can take a look at the MockTests classes in the openstack-swift api to see an example of how these tests work.
Often the best thing to do is to copy the entire directory structure of one of the existing apis or providers and delete everything that you don't need but keep some of the files around in each directory to server as an example of how to do things. You can rename those classes and start your work from there.
Which api or provider should you choose to use as an example for your work? It depends! Please email us on our dev# list to describe the work your doing and we will recommend one. The earlier you get engaged with the jclouds community, the easier the whole process will be.
Good luck!
I was reading through the RABL git https://github.com/nesquena/rabl and I quickly came across this line. Can someone quickly explain what he means by "generating APIs"?
When using the ActiveRecord 'to_json' method, I tend to quickly find myself wanting a more expressive and powerful solution for generating APIs.
From my understanding an API is a set of classes / methods that may be used to interact with the content of the API creators material. With that definition, I believe he is saying that he wants to be able to interact easier with the API so he build RABL which allows for the content to be translated from his application to, in this case, Rails eaiser?
In this case, API is applied to the system as a whole. So your entire website might have an API that your customers would use to pull/send data to your system.
Mostly, these are JSON/XML endpoints that accept and return data. Rabl (and other serializers like it), help you craft custom JSON responses.
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.