These days everyone is making REST applications. So far i used only swagger editor for generating those files.
Does anyone know if there is good mature tool or IDE that thave ability to visually design Swagger REST APIs and then generate the Swagger Specification YAML specification file?
Tool can be commercial or opensource
I am using https://studio.restlet.com for that.
It is a great tool and it is pretty in intuitive..
You can do export/import from Swagger and RAML.
I'm using postman for testing api. Postman collections can be exported and transformed to valid Swagger 2.0 YAML on https://apimatic.io/transformer.
Exported YAML file then import on swaggerhub https://app.swaggerhub.com were changes can be made if needed.
Folders from postman are transformed into tags, request models are generated by body of request and response examples can be used to document different error responses.
Related
I'm looking to get familiar with the Amazon Connect API. I've seen the reference below but it's difficult to use for me because the navigation is a flat, alphabetical list of endpoints ordered by action instead of resource. Of note, the endpoints are alphabetized beginning with "Delete", Get", "List", "Update" and others, while it would be great to have these grouped by resource.
I'd like to reorganize the docs which can be done by editing an OpenAPI or other API specification and adding tags for each operation. I looked though the reference and conducted a few searches unsuccessfully.
I'm using the following API Reference:
https://docs.aws.amazon.com/connect/latest/APIReference
Any other spec format such as RAML or a proprietary format would be okay as well. For example, Google provides their own "Google Discovery Format" which can be converted to OpenAPI. The following is mentioned at https://googleapis.github.io/ .
OpenAPI
We recommend using OpenAPI and OpenAPI-based tools for working with Google’s REST APIs. Several tools for converting Google Discovery Format to OpenAPI have been published:
google-discovery-to-swagger, an MIT-licensed open source script for converting Google Discovery format into Swagger 2.0.
API Spec Converter, an online converter from LucyBot.
The API Transformer from APIMatic.
Google’s OpenAPI tools include gnostic, a front-end for OpenAPI tools that reads OpenAPI descriptions, puts them in an efficient binary representation, and allows efficient plugins and standalone tools to be easily written in any programming language with Protocol Buffer support.
Is there an OpenAPI or other spec available for this API? If there is, I'd like to update it with tags and then render it in an easier to consume format.
Update: Aossey notes that Amazon doesn't publish OpenAPI specs for their APIs. To address this, I've started to assemble some information in the repo below, potentially resulting in an OpenAPI spec. Feel free to contribute.
https://github.com/grokify/amazon-api-specs/blob/master/connect/endpoints.csv
The short answer is no, there is no OpenAPI spec for these APIs.
These functions (listed in the docs you linked) are implemented in AWS SDK and the AWS CLI. While there are underlying HTTP endpoints, they are not easily consumable in the way you're most likely looking for. The SDK and CLI take care of authentication/authorization (via IAM service) and request signing for you, which you would have to implement yourself if you were going to leverage the endpoints directly.
I'm currently working on developing connector for the surveymonkey Rest API. Is there any OpenAPI Specification file for the same that has all the endpoints as per the docs? If not, can I get it in the near future?
In researching the same question, I discovered that you can export the Survey Monkey collection from Postman as a JSON file, then convert it to OpenAPI format using this tool: https://kevinswiber.github.io/postman2openapi/.
Postman is working on a new feature to make this functionality available directly within their tool as well.
I know that REST doesn't have WSDL document as SOAP has (some has WADL but not all, and it is not that common)
Is there a tool that take REST documentation (REST uri maybe) and generate describing document for that web service?
The tool swagger https://editor.swagger.io/ is able to do it only if added annotation to the source code of the web service not to any REST web service.
In short there is no official/REST approved way of doing what you are looking for.
WADL, Swagger and RAML are all "proposed" ways of achieving WSDL like functionality in REST, however they are proposed and not wildly supported by the development community.
If you were to start a new project these would make sense but if you want to run it on top of a existing project and generate some documentation you are pretty much out of luck.
Spring REST Docs was released recently and the documentation says:
This approach frees you from the limitations imposed by tools like Swagger
So, I wanted to ask when Spring REST Docs is preferable to use comparing to Swagger and which limitations it frees.
I just saw a presentation here that touches on your question among other topics:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger doesn't support hypermedia at all / it's URI centric
Swagger's method of inspecting your code can lag behind your code. It's possible make a change in your code that Swagger fails to understand and won't process properly until Swagger gets updated.
Swagger requires lot of annotation, and it's painful to include the descriptive text you want in an api document in annotations.
There are just some things that Swagger can't figure out from inspecting your code.
In any case, these are just a couple of points. The presenter does a much better job discussing it than I could.
I thought I would chime in to give a little bit more context surrounding Swagger, what it is, and what it is not. I believe this might help answer your question.
Swagger 2.0 is being adopted by a lot of big names and big platforms like Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com, etc... Something to keep in mind is that Swagger is very simply a specification. It is not a framework. There are a lot of frameworks out there built to generate Swagger output that crawl through your code looking at your API information in order to build the Swagger 2.0 JSON file that represents your API. The Swagger UI that you see your APIs on is driven directly from this Swagger 2.0 JSON file. fiddler it to check it out
It is important to note that a framework that was created to allow you to "use swagger" is not how Swagger has to work (i.e. it is completely up to the implementation of the 3rd party framework). If the framework you are using to generate your Swagger 2.0 documents and UI is not working for you then you should be able to go find another framework that generates the Swagger artifacts and swap the technologies out.
Hope this helps.
From Spring REST docs:
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST docs advantages:
Documentation is written in the test code so it does not overload main code with lots of annotations and descriptions
Generated docs and examples are accurate because related test must pass
Docs can provide more specific and descriptive snippets
Format is suitable for publishing
Spring REST docs disadvantages:
Requires more work
Documentation provides request/response examples but don't provide interactive tools to modify and try out requests
Swagger advantages:
Quick, automated generation from a code
Interactive request execution - can be used for acceptance testing
Built around the OpenAPI Specification
Swagger disadvantages:
For more descriptive documentation it will require a lot of annotations
Tests are not related to the documentation so sometimes documention may deviate from reality
There is some limitation with swagger and the specific spring stack.
For example : with "param" in your Request Mapping you can define more than one method with the same url ans so simplify your code.
But swagger show you just one method
One disadvantage with Swagger is: it cannot handle models which have cyclical dependencies. If a model has cyclical dependency and if swagger is enabled, then spring boot server crashes.
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.