Documenting RESTful APIs
Why Stack Overflow recommends it
Stack Overflow users link it when comparing Spring REST Docs with Swagger, and as a tutorial for setting up Spring REST Docs builds, including its continuous-build segment.
Recommended by 2 people across 2 different months, 2016 to 2021.
What it is
A SpringOne2GX 2015 conference talk by Andy Wilkinson on what good RESTful API documentation contains and how to structure it. It compares Swagger's limitations with alternatives like Spring REST Docs and demonstrates the latter.
What people said
Recommends Edgar Ngwenya · 2016-01 · Stack Overflow · on “What is the benefit of using Spring REST Docs comparing to Swagger”
I just saw a presentation here that touches on your question among other topics: [this video] 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.
Recommends yejianfengblue · 2020-07 · Stack Overflow · on “Swagger 2 or 3 for Spring Data Rest”
I recommand Spring REST Docs [LINK] over Swagger. Spring REST Docs is test-driven to guarantee your API documentation is always sync with your API. Andy's talk [this video] explains more why Spring REST Docs is more suitable than Swagger for API documentation. You can find offical simple guide [LINK] and more samples [LINK] . My Github project [LINK] uses it. You can clone the repository and have a look at the generated documentation HTML /sga-booking/index.html [LINK] . Related Spring REST Docs file are FltApiDocumentation.java [LINK] flts.adoc [LINK] BookingApiDocumentation.java [LINK] booking.adoc [LINK] If you find my Github useful, consider give it a star.
Cites Eric Huang · 2018-11 · Stack Overflow · on “Spring REST Docs maven continuous build?”
I was going through this tutorial [this video] Around 1:07:30 the author mentioned about "Gradle has continuous build" later on was able to detect changes in the test and automatically regenerate asciidoc. I was wondering if anyone knows how to set this up in maven? I have looked through docs in spring and asciidoctor plugin, but was not able to find anything related to this. I was able to get maven to re-render html when ever there is a change in index.adoc by changing <goal> from process-asciidoc to auto-refresh . However, this does not watch the change in the Test. Question Is there a way to tell Maven to watch our test files and re-compile when changes are made? POM.XML <plugin> <groupId>org.
Cites Eric Huang · 2021-02 · Stack Overflow · on “Spring Rest Doc (Gradle) Snippets disappear upon build”
Recently switch to Gradle from Maven. Following this tutorial for continuous REST Doc build with Gradle. [this video] Snippets are generating just fine when running test. Its when I am trying to generate asciidoc where it seems like the /build directory gets recreated without the snippets. So my generated html always shows Unresolved directive in index.adoc - include::{snippets}/home-json/curl-request.adoc[] I am generating the asciidoc by the following command in the terminal gradle asciidoctor -t // Continuous build command // Mentioned around @1:07:40 mark // [this video] build.gradle plugins { id 'org.springframework.boot' version '2.4.2' id 'io.spring.dependency-management' version '1.0.11.RELEAS