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
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
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.
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'm looking at Spring REST Docs and wondering if it has the ability to interrogate #RestController methods to produce basic documentation describing a Rest API (methods, http method, parameters, response type)? I believe Springfox Spring/Swagger does that, and would be easier than having to write a test to get that basic info/documentation.
Also, since I don't want to run integration tests in a Production environment, is the Spring RestDocs approach to run your integration tests in a Test environment and then copy the generated docs/snippets into the war so it can be viewed in a Prod environment?
I'm looking at Spring REST Docs and wondering if it has the ability to interrogate #RestController methods to produce basic documentation describing a Rest API
Spring REST Docs is test-driven and deliberately doesn't take the approach of introspecting #RestController methods. You REST API documentation is describing HTTP requests and responses. By being test-driven and working with real or mocked HTTP requests and responses, REST Docs ensures that what you're documenting is what users of your API will be dealing with.
The problem with introspecting #RestController methods is that it's only one small piece of the puzzle. When an HTTP request is received it passes through filters, interceptors, HTTP message conversion etc before it reaches your controller. The same is true in reverse when a response is being sent. Without a complete understanding of everything that happens before your controller's called and everything that happens after your controller returns, the documentation is at risk of being inaccurate.
is the Spring RestDocs approach to run your integration tests in a Test environment and then copy the generated docs/snippets into the war so it can be viewed in a Prod environment
Correct. The documentation is generated once at build time and then typically served as static files from your application. Details of how to do this with Spring Boot are included in the documentation.
This approach has the advantage that none of the code that's involved in creating the documentation is running in production. That reduces your application's footprint, and avoids the possibility of the code that's generating the documentation from causing a problem in production. I believe you can take a similar approach with code-first Swagger tools but, in my experience, it's unusual for people to do so.
Swagger is best choice for me. You cannot do make docs with Spring Rest Docs without integration tests. It's good article reviews rest tools
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