Does anyone know of a link to a useful documentation on how to add swagger documentation to an existing aws lambda (API Gateway)? Some sort of a noob tutorial as I am totally new to swagger.
I have found some links, such as the following, which were not so useful or not specific to lambda:
https://blog.cloudboost.io/adding-swagger-to-existing-node-js-project-92a6624b855b
https://github.com/swagger-api/swagger-node
I have only used Swagger with API Gateway with the old v0.5 version of serverless framework as there was a plugin that supported this easily.
However, when serverless matured into v1.0 and up, at that time, there were no good plugins for Swagger integration.
Here are links you can check:
Serverless Github Issue: Swagger Integration
Reckon-Limited/serverless_swagger
doapp-ryanp/serverless-plugin-swag
I don't personally use the above though as my big serverless projects are now using GraphQL (where API documentation is part of the standard tooling :-) instead of REST.
In my backend team we do the documentation using a tool that smart bear makes available, the swagger inspector and through it we finish adjusting the doc with the swagger hub.
Swagger inspector makes a request on your endpoint and basically extracts the necessary documentation, but some things you need to adjust, it is not the best solution, but it helps ...
Related
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
Is it possible to generate a Swagger documentation for my ASP.Net Web API in a separate project?
I created an empty project where the Swagger documentation should go. In the API project the Swagger project is referenced, but didn't work.
Than API project is load like an external assembly. The controllers was reachable, but documentation wasn't generated.
Then tried with the automatically generated XML documenatation, just to see if it will create anything, but there is no result.
After this try like to have multiple API in one Swagger documentation, Multiple API documentation in one Swagger file, wasn't work.
I also tried this:
ApiExplorer for WebAPI controllers in external assembly
https://github.com/Microsoft/aspnet-api-versioning/issues/271
On the Swagger official documentation I didn't find something that could help me with this. Neither did I find any information elsewhere if this is possible and how it needs to be done.
I use Swashbuckle 5.6.0 and ASP.Net Web API.
Yes, it is possible to generate Swagger documentation for a Web API in a separate project.
Here I have the code showing how I did it:
https://github.com/heldersepu/csharp-proj/tree/master/Swashbuckle.Sample
And here is how the swagger-ui looks like:
http://swashbucklesample.azurewebsites.net/swagger/ui/index
To be honest Nothing special about that code, it worked on the first try for me ...
But I do have some experience with Swashbuckle
If you can provide a minimal project reproducing your issue, we can help you get to the bottom of it together.
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 have seen this Spring REST Docs - video
We are doing Spring boot projects and are using springfox library for generating the Swagger-ui and swagger documentation as outlined here
We like what Spring Rest docs can do for generating REST API documentation and the fact that we don't have to add swagger annotations like #ApiResponse or #ApiOperation in our Controller code. And also the fact that the documentation now lives with the code.
But if go with Spring Rest docs, we will miss out on the Swagger-UI that gets automatically generated for our API (when we use swagger integration).
Is it possible for Spring REST docs to generate a test UI like Swagger UI.
That pretty directly goes against the design idea and intention of Spring REST Docs. One of the main goals of it is that the docs are tied to unit tests so you know your documentation is rock solid even when you make logic or signature changes in your REST contract.
Also as the video you linked to provided a number of examples of how automated docs generation produces a lot of undesirable un-intended output.
So its a choice of do more work to get much better docs, or do the fully automated option to save time and get workable, but lower quality docs. It is what ever your priority is.
This project generates an OpenAPI specification from Spring REST Docs.
https://github.com/ePages-de/restdocs-api-spec
There is a number of good documenting tools for Django REST Framework, especially Django REST Swagger: http://www.django-rest-framework.org/topics/documenting-your-api/
All of them are for online usage. Is there a tool to generate offline documentation: PDF or a collection of HTML/CSS-files? Something like http://sphinx-doc.org/ does?
Assuming you've the Swagger spec file (JSON/YAML), you can use Swagger-Codegen to generate the static documentation for your REST API.
UPDATE: On May 2018, about 50 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen to maintain a community-driven version called OpenAPI Generator. Please refer to the Q&A for more information.