Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I have a setup where it is possible to get some resource using standard REST and this is easy documented in swagger. The same resource is pushed to clients using websockets when it has changed, so clients does not have to do a pull on an interval basis.
But how can I document this in swagger? Is it even possible? If not, what other tool do you recommend for documenting both the REST api and the websocket part?
OpenAPI 3 (aka Swagger 3) has an upgrade in the response formats where they added the concept of callbacks, which allow you to define a webhook. Take a look at this part of the documentation: response format.
In Swagger 2 what I use to do is to implement an API method that implements exactly the same I expect from a callback and I just reference it in the original method that waits the callback. So any consumer can at least see the format of message that I'm expecting from them, using the Swagger specification.
It is difficult today to find a clear answer on "How to document apis using async communication". It is not only about websocket but also Server Send events and others....
Today, for Rest specification, there are many famous specifications and the top 3 is:
- Swagger
- RAML
- API Blue Print
They are a lot of issue/discussion about a way to document apis using websocket,...
But Swagger is standardizing api specification with the help of the community. It's named OpenApi.
The version 3 of the OpenAPI specifications introduce a way to document webhook/callback.
Another good specification is asyncapi.com which is going deeper and respect the readeable openApi specs.
The Swagger spec defines a limited set of operations, which you may define for a particular path object in your schema. That being said, you are free to step outside of the spec if you only care about documenting your API for human use. Take a look at WIX docs for example. It uses a custom HOOK definition to document its webhook API and it doesn't pretend to be a valid Swagger spec, which may be just what you need in your case.
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
My team and I are currently building multiple services in parallel. We have the benefit of building all the services from scratch. I would like the ability to automatically display all API endpoints, from all services, in one page/site. This would be helpful because (among other things):
I don't have to go to multiple documentation sites to see what are the available endpoints in my entire "system".
It'll be a good first step to determine if any of the services should be split, combined or simply refactored.
Some of our services are in Django and the rest-swagger module is a great help. But I don't see how I can combine rest-swagger documentation from multiple services into a single documentation page/site.
I'm currently looking through this site and anything related to the Netflix experience but could not find a solution to my problem. Maybe centralized documentation isn't a big deal with 600+ services at Netflix, but that's hard to believe.
Can anyone suggest a tool or method to have a combined API documentation for all services in a microservice architecture?
My ideal scenario of what happens when a service is changed:
I click on the link to see the list of endpoints in my system.
A teammate updates a service and also it's documentation.
I refresh the page I am currently and I see that change made from step #2.
With my exp, you have some paths.
http://readme.io/
Make a wiki with JIRA, Redmine.
In Github create a repo for exclusive docs.
Google Docs.
I don't know about any existing tool rather I'm just putting my thought on where to do it.
From what the OP describe, they are already building a micro services architecture using Netflix stack. There should be a repository to config the name (or URL) for each of the services and the 'config server' or 'service registry' will read from that. To me, that's the perfect place to put the reference to each of the micro-service's documentation under their own entries. This way you get the benefit of maintaining the documentation and code at same place, plus you could potentially also collect run time information like instance/connections count if you hook into the config/registry server.
Being in similar situation I am looking to adopt https://readthedocs.org/ with GIT backed.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
I want to be able to contribute to Google Translate on my native language (Sinhala).
Although there is an online portal (http://translate.google.com/community/) where we can contribute to the translator by translating new phrases or validating existing translations, I would like to create my own, lightweight portal (maybe an Android app) for the contribution service. However, I was unable to find any public API for the translate contribution platform, despite a thorough Google search and a full search through the Google Translator Toolkit API forum (https://productforums.google.com/forum/m/#!categories/translator-toolkit-api) (which seems to have been closed down since the end of 2012).
Currently my best hope is to mimic the request-response sequence followed by the online portal itself. For example, the following request is used by the online portal to fetch a question list for manual translation:
GET http://translate.google.com/community/question_list?sl=en&tl=si&client=t
However, it requires that all the related cookies are properly initialized and passed with the request, which would probably not be easy to mimic in a non-browser environment (such as an Android app). Hence I believe there's a better approach (maybe a yet undocumented API?) somewhere out there.
Does anyone know of any API for accessing this translation contribution feature?
Thanks in advance.
Please note: I am NOT looking for a way to improve Google Translate itself, but for contributing to the actual translation content as described under "How can I help?" in the Google Translate Community FAQ (https://docs.google.com/document/d/1dwS4CZzgZwmvoB9pAx4A6Yytmv7itk_XE968RMiqpMY/pub#h.e1ahmpftpdum).
P.S. I was initially planning to post this question on the Web Apps Stack Exchange, but after reading this post I decided to first try it here.
I'm one of the engineers behind Translate Community and I'm really excited that you want to see it on more platforms. We're currently under active development of the site and making it more accessible on mobile platforms without having to create dedicated native apps.
For the time being, we don't anticipate releasing a public API as the platform is under active development. Until we do release a public API, please don't use any http commands you find to create a separate app. Instead, just let us know how we can make the app a better experience for you and we'll work on making it better.
Thanks!
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I've been looking for automatic creating the documentation for the REST API of a project I'm working on. First, Hydra (http://www.hydra-cg.com) shows up with an interesting idea for designing Web APIs. Later some colleagues recommend me to use Swagger 2.0 (http://swagger.io) as code generator. Then, I realise that both specifications can solve the same problem of documenting the REST API.
What are the downsides/benefits of using Hydra or Swagger specification?
Thanks!!!
Swagger is well established and supports a wide range of languages and frameworks. It doesn't force you to write the API in a specific style and it should be a better fit if you just want to document an existing API.
Hydra looks like interesting framework to develop REST APIs but has yet to be adopted by any standards organizations and the industry to make it a real standard. It's just an unofficial draft by a W3C community group for now. It also seems very new and provides experimental tools for some languages, which don't seem ready for production. I'm not even sure if you can integrate the framework with an existing API without changing the API significantly.
As stated by inf3erno, Hydra is more focused on the original definition of REST services and generated documentation is just a byproduct. On a first glance it seems to me that they are using principles similar to HATEOAS and try to formalize that technique using vocabularies. I think there is good reason to stay with the more simple modern definition of REST services though and don't make development to complicated by adding HATEOAS or vocabularies.
Hydra is about creating a REST specific vocab, so after it became a standard, every REST API can use that vocab, and it will be possible to write general REST clients, just like browsers are for human users on the web currently. That is real REST. Current so called REST APIs don't fulfill the uniform interface constraint, because they use non-standard solutions. Hydra will solve this problem. It's just an insignificant detail, that it is possible to generate documentation from an API specific vocab if it is described with hydra terms.
A don't know what swagger is, but it appears to be a non-standard solution to the same problem.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 8 years ago.
Improve this question
Many questions being asked about generate Rest API to html documents.
But eggs comes from chicken.
In many cases , the architecture needs to define the API . It's a connection between web developers and iOS/Android client developers.
So is there such kind of tool or web , we can do follow things:
New a API
write the subURL
write the POST/GET method
write the post parameters
write the returned answers
write the sample request , any kinds of condition, error codes.
After all this, there is a doc or Online doc html there.
We can edit , update it after times pass by. The web/client developer , just need to watch the document ,then they are ready to go.
Is there any kind of tool can archive this ? Thank you.
There are a couple of specs for documents that allow clients to discover RESTful APIs.
Swagger (demo)
apiary
JSON Home
Google use their own Discovery Service, however unlike the others, unfortunately I don't think there are open sourced libraries that help you use expose it from your own APIs.
I have used swagger and it works well. The spec handles the things you have mentioned:
JSON Schema to describe request/responses
A list of error codes/conditions
A codegen library to generate client side code for a number of languages such as Javascript, Java, Objective-C, Scala, PHP, Python, Ruby, and more.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm looking for a nice way to generate documentation for a REST API. It doesn't need to actually connect with the code or anything, but it'd be awesome to be able to write the documentation as text files, point the tool at it, and generate some docs from it.
Anyone out there have any ideas? I know I'm being a bit vague, but, to be honest, I'm not quite sure what I'm looking for here--mainly an easy way to manage documentation.
According to Roy:
"A REST API should spend almost all of its descriptive
effort in defining the media type(s) used for representing
resources and driving application state, or in defining
extended relation names and/or hypertext-enabled mark-up
for existing standard media types."
Self-descriptiveness is one of the benefits of REST.
While not REST, I used Sphinx to document an XML-RPC API that consisted of an API reference and a tutorial. Sphinx adds some handy directives to ReStructuredText to get pretty much what you asked for: a collection of ReStructuredText formatted-text files that Sphinx turns into HTML and PDFs, complete with an index and table of contents. Sphinx is easy to use and well-documented; I don't think it would be an exaggeration to say you could get started with it in about ten minutes.
Some RESTful systems are actually able to write their own API. Have a look at RESTx, which does just that: You write your components and then create new web services by sending parameters for those components to the server (either as JSON or via a web form). You then get a URI back for those parameters. Accessing it calls the component with the parameters and you retrieve the results.
At any rate, the components as well as the created RESTful web services get an automatically generated documentation, which is browseable and can be retrieved either in HTML or JSON format.