suppose that we have some Swagger 2.0 document, e.g.
http://petstore.swagger.io/v2/swagger.json
I am trying to convert it to another formats using Apimatic.
https://apimatic.io/transformer
If I convert the Petstore Swagger document to WADL, the result seems to be invalid.
I have validated the WADL file against
https://www.w3.org/Submission/wadl/wadl.xsd
Generally, I need to convert Swagger either to WADL or to RAML.
I am trying conversion from Swagger to RAML with Apimatic as an alternative because the convertion to WADL did not work.
Is there a way (online or offline tool) to check that the resulting RAML file is valid?
Thanks.
Online: the "Design Center" at https://anypoint.mulesoft.com
Offline: go to https://raml.org/projects and click on the Design tab
Also in the latter check the "Utilities" tab, there are swagger to RAML converters there.
Related
Is there a way to generate OpenAPI spec files from a gin project? This issue is really hard to search for, all I could find so far are on doing there reverse.
gin-swagger is extracting comments from your code.
Running swag init generates :
docs.go: To serve SwaggerUI pages
swagger.json: The Swagger Specification in json file format.
swagger.yaml: The Swagger Specification in yaml file format.
You mean API docs for API user?
I saw you tag the question with swagger.
You have two chooses:
go-swagger
This package contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
swag
Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular Go web frameworks. This allows you to quickly integrate with an existing Go project (using Swagger UI).
What difference between them?
Here is the answer from go-swagger:
The main difference at this moment is that this one actually works...
The swagger-codegen project (like swag) only generates a workable go client and even there it will only support flat models. Further, the go server generated by swagger-codegen is mostly a stub.
Detail of this answer in How is this different from go generator in swagger-codegen?
from go-swagger.
For my springboot project, I am using OpenAPI 3.0.3 and springfox(3.0.3) for API documentation. I would like to generate the API documentation in YAML format, not JSON. By default, springfox generates JSON.
I have looked into using springdoc-openapi-ui instead of springfox (springdoc has the option of YAML format), but then I have to change all annotations and so on.
I was wondering if there is a way around it for telling springfox to generate yaml instead of json.
Thank you!
There is already a github issue with this query. Check out the discussion here for various possibilities -> https://github.com/springfox/springfox/issues/985
Another approach could be to take Springfox JSON and convert it to YAML using JSON2YAML converter as in https://www.json2yaml.com/.
I am new to Spring-Boot. I want to auto generate my REST api documentation into RAML from my Spring MVC controllers. Is there anything to do that? or any guide that I could use it for generating my rest api into RAML?
There is a Spring REST Docs to RAML extension for Spring REST Docs: https://github.com/ePages-de/restdocs-raml However, this project is not maintained anymore and the authors recommend to use their new project https://github.com/ePages-de/restdocs-openapi that converts to OpenAPI (Swagger) instead of RAML. They provide a guide on how to convert OpenAPI to RAML: https://github.com/ePages-de/restdocs-openapi#convert-to-raml There is an example project that demonstrates the conversion to OpenAPI and RAML https://github.com/ePages-de/restdocs-openapi/tree/master/samples/restdocs-openapi-sample One limitation of the extension is that it only works with Gradle at the moment.
I know, your Question is outdated, but there is something that might help.
You can use DocDog. From there it creates RAML from the existing source code. If it is SpringBoot you can run it easily with -lang=spring. If it is plain JAVA you can add comments to your code (see readme.md or examples), so DogDoc can understand.
May it helps you: https://github.com/skalski/docdog
I am starting to use Spring REST Docs but I miss a nice feature of swagger... the "try it out!" button that includes a HTML form to test the API. I get the curl link OK; but I usually use swagger form.
Is there a simple way to do this in Spring REST Docs?
Thanks
I solved it for myself by creating a tool to convert Spring REST Docs cURL snippets to Postman collections. It's available as a npm package: https://www.npmjs.com/package/restdocs-to-postman that can be used on the command line and as a library. This is one solution for https://github.com/spring-projects/spring-restdocs/issues/47. In my opinion tools like Postman are good to try out APIs.
Edit: There are converters from Postman and Insomnia to Swagger. So with two conversions (restdocs to Postman/Insomnia and Postman/Insomnia to Swagger) one can get a Swagger playground. This is not optimal, but works.
Examples for converters:
Postman to Swagger: https://apimatic.io/ (paid service with trial)
Insomnia to Swagger: https://github.com/mlabouardy/swaggymnia (MIT license)
Edit 2: I have created instruction on how to create a Swagger playground out of Spring REST Docs: https://github.com/fbenz/restdocs-to-swagger It takes a few steps and would be simpler if Spring REST Docs would directly produce a Swagger file, but it works and can be automated.
No, the closest I believe it can provide is a curl with an example request. There is an open enhancements to provide Postman collections, https://github.com/spring-projects/spring-restdocs/issues/47, but nothing as simple as Swagger's try it out!
Also somewhat related from this ticket, https://github.com/spring-projects/spring-restdocs/issues/213,
I'm rather torn on trying to add support for generating a Swagger specification. When you describe Swagger as providing an "API Playground", you've drawn a very important distinction that many others do not. I firmly believe that Swagger's UI is not a substitute for API documentation and using it as such isn't good for a service or its users.
My fear is that if Spring REST Docs provided support for producing a
Swagger specification, people would then use that specification to
populate Swagger's UI and consider their service to be documented.
It's a matter of weighing up trusting people to do the right thing,
versus encouraging people to shoot themselves in the foot.
I can easily validate a XML document against a XML Schema, eg. with XMLSpy or programmatically.
Is it possible to do this with a WSDL file? It does not seem possible with XMLSpy or any other XML tool I know. For me the only possibility right now is to do it programmatically, eg. by generating Java code from the WSDL and starting a request, which is then marshalled correctly.
If there is no tool / easy programmatic approach, is there a tool which can extract XML Schema from the WSDL?
Best
You could use SoapUI :
Create new project (you'll need to provide wsdl)
Double click on the "request" of your new project
Modify XML if needed
Right click -> validate
QTAssistant (I am associated with it) provides an easy to use utility to extract XSDs from any-style WSDL (single or multiple file, internalized or externalized XSDs).
The prompt is pretty straightforward to follow, and provides a lot of flexibility in referencing offline WSDLs (local disk) or remote (HTTP/S).
Another feature that works well with the above set is the ability to validate a SOAP envelope against an XSD, also available within QTAssistant; there's a property Strip SOAP for an XML document that'll automatically validate SOAP Body content against assign XSD.