I am using Swagger for REST API documentation which is built using Spring Framework. I am looking for better alternatives where I don't need to define complex resources again and again in every API.
Like Google has a well-defined documentation Google Doc. What frameworks top IT companies using for it.
Well I have advised two of those companies to use OPTIONS.
OPTIONS data can be cached at runtime giving a custom APIDOC per each ROLE/AUTHORITY.
That way USER will not see ADMIN endpoints and you can create a dynamic APIDOC.
Related
I have several services, each one exposed through REST API with ASP.NET Core Web API. I use Swashbuckle for ASP.NET Core tooling in order to automatically generate from my controllers and DTOs all the necessary documentation and visualize it in SwaggerUI. I found this tooling really great, with little annotations on my models and my controllers already provides many features out of the box, such as a UI client to try out the REST API endpoints.
But with this solution each service has its own dedicated SwaggerUI instance and therefore UI.
I would like to offer to my customers a wiki-like documentation with a navigation menu, where, for instance, they can browse sections regarding all the endpoints exposed by my services and have on each page the same features offered by SwaggerUI.
It can be achieved by creating my own web application but I was wondering whether an out of the box solution or some tool that might ease such integration already exists.
I tried Slate but I felt like I had to re-invent the wheel in order to automate at least the creation of the basic API documentation, namely controller definition, response definition and descriptions. Does anyone have any suggestion?
I faced this very issue recently working in a microservices architecture, you're absolutely right. There is not need to reinvent the wheel.
I really can't recommend redoc by Redocly enough in this case.
Have a look at the multiple-apis example.
I have spent days looking for proper comprehensive documentation for the JavaScript client library for the Google Analytics API. The only bits I could find was this page: https://developers.google.com/analytics/devguides/reporting/core/v4/rest/ which has all of ~20 completely uninformative words on the page, and https://developers.google.com/analytics/devguides/reporting/core/v4/quickstart/web-js, which does have some actual JavaScript, but nothing like documentation. It just illustrates two or three functions using the client API.
Is there nowhere that they actually list the full API? How are we supposed to know what functionality is available?!
Then there are the pages in this section: https://developers.google.com/analytics/devguides/reporting/core/v4/basics#request_body which list a lot of query samples, but don't explain how to use any of this in a client library. Is there any practical information on how to get started with accessing the Analytics API anywhere?
Thanks
The Analytics API is language agnostic, the google js client library docs apply to all of Google's APIs. Every client libarary is built around the discovery service API which describes the entirety of whats is available.
V3 API discovery call
Analytics Reporting Discovery call
How to use a client library is centrally documented and applies to every Google API.
Analytics Specific
There are lots of languages and client libraries and the Analytics API team cannot support every language. Instead they make available comprehensive reference docs which describe what endpoints are available. Once you learn how to use a particular client library calling the individual API endpoints happen in the same why.
That being said every endpoint they have is documented in JS.
The Analytics Mangement API is well documented in JavaScript. the Open source Google deomos and tools is built with it.
The Analytics Reporting API Samples page has documentated examples in JavaScript. You even linked to a Quickstart guide which should help you understand how to use the client library.
Can you expound more on what you'd expect in terms of documentation?
Final tip
If you load the analytics client library
gapi.client.load('analytics', 'v3').then(...)
In the chrome console you can then just start playing with it dynamically:
gapi.client.analytics.managment.[hit tab]
will list all the management API methods available.
I'm trying to use the Swagger UI, and it says that I should begin by writing an api-doc that describes the exact api for a REST api. The problem is that I have no idea what this means. Is this document written in plain English? Or is there a certain format that will be able to generate the UI?
Thank you!
Swagger is a specification for describing REST APIs. Documentation of the specification can be found here - https://github.com/swagger-api/swagger-spec.
Generally, there are two ways to document your API. If you already have an existing API with code, you can use any of the existing libraries (https://github.com/swagger-api/swagger-spec#additional-libraries) to integrate into your code and generate documentation at run time. Some of those libraries also offer offline generation of such docs.
If you're looking to design an API, or would rather not integrate another library into your application, you can use https://github.com/swagger-api/swagger-editor either locally or with the online version - http://editor.swagger.io.
Once you have the documentation, you can use Swagger UI to visualize and test it.
I've just started on a small project to create some REST services using Google App Engine and Java. I'm new to both technologies, but I've done some reading on both. I'm familiar with SOAP (have used them previously), and I think I understand the conceptual differences between REST and SOAP.
Currently I need info regarding two things:
1) I'm trying to find some tutorial which builds a simple REST service from scratch for deploying on Google App Engine (GAE). The simpler the better, but it should have at least a few routing options. I don't need any UI, if that matters.
2) Which RESTful Framework should I use with Google App Engine. Again, simplicity is what I'd like, and something which has tutorials and a newcomer can easily grasp.
My ultimate goal is to just write a REST wrapper with multiple routing options, which eventual consumes some pre-existing SOAP services and returns their results.
Have you checked out Google Cloud Endpoints for creating a REST service? Its pretty simple and straightforward, also has support for OAuth.
I would give Jello framework a try. It offers a clean, and simple to follow, JSON format and provides a very powerful and comprehensive RESTful implementation that follows the OData specification.
Here is Jello's REST development guide: http://jello-framework.com/guide/rest.html
What are some web apps that allow me to play with any REST APIs visually (by clicking) and also get some code generated (in any language) that captures what I have described visually?
Similar to Swagger or Google API Playground but allows me to talk to anything that speaks REST (assuming I have the proper auth credentials and I know what messages it understands).
Bonus points for something that can also "discover" what messages are understood, given a URL endpoint.
Microsoft has 2 that I know of
OData API explorer
The data market service explorer (requires signing in, and then you can access free data sets)
Considering that REST API's are going to follow their own conventions, terms, and have their own documentation (hopefully), this is an impossible problem. If you restrict your quest to visualizing API's that follow a "standard" form of self-documentation (see REST web service WSDL? for some hopeful scenarios) you might be able to accomplish this.
Or you can use something like http://www.programmableweb.com/ to discover tutorials, tools, examples, and mashups of various existing APIs.
You could mock an API at http://apiary.io/.
You could explore and existing one through tools (e.g. REST Console for Chrome)
What you can't have, is one-size-fits-all explorer for "every possible REST API." Some APIs follow conventions that others don't.
apigee and apihub (now part of mulesoft) are two that I frequently visit. Of the two, apigee is my preferred provider.
One of the reasons that you're not going to see a lot of websites like this is because of the same-origin policy. This means that you can't access a RESTful API located at api.google.com from a web app running at, say, www.restfiddle.com without sending all the API traffic through restfiddle.com's servers. Sites like JSFiddle can exist (and are used widely) because all the processing is done on the client side.
Browser plugins, however, are exempt from the same-origin policy. If you're using Chrome, try Postman. If your REST client doesn't need to be web-based, check out SoapUI. IntelliJ IDEA has a nice REST client as well.
Try Restlet Studio, it's the only visual API designer I've found, and seems pretty good, it imports and exports swagger & RAML.
http://studio.restlet.com/