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
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.
im currently thinking how to build REST API docs for my application with support for multiple languages. Endpoints, parameter names and return values should stay the same but the description of each REST method i want to provide in different supported languages.
Im using Spring boot, data & rest and found this docs project what seems very useful to me. Anyway, i couldn't find any informations in the docs regards the i18n topic/support.
Does anybody know if Spring REST docs support the generation of the API doc for multiple languages (in general)?
REST Docs doesn't provide any out-of-the-box support for I18N but it should be pretty straightforward to build something on top.
The main piece with which REST Docs is involved and that I think you'd want to translate are the descriptions that are included in the various snippets. Rather than hard-coding a particular description, you could look each up in a ResourceBundle:
ResourceBundle resourceBundle = ResourceBundle.getBundle("field-descriptions");
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("example", responseFields(
fieldWithPath("a").description(resourceBundle.getString("a")),
fieldWithPath("a.b").description(resourceBundle.getString("a.b")))));
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
Whole idea is to create Mock service for UI guys to test without actual api.
- We have define specification in .ymcl files.
- Now want to generate Swagger-UI and Mock rest URI with mock data.
- Using spring-boot.
Please suggest some way to generate the same.
Given that you've the API documented in Swagger/OpenAPI spec (YAML format), you can use Swagger Codegen to generate Spring boot server stub.
Please pull the latest master of https://github.com/swagger-api/swagger-codegen and follow the instruction in the wiki:
https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO#java-springboot
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.