Visualize and document REST APIs
Last updated
Was this helpful?
Last updated
Was this helpful?
Swagger is widely used for visualizing APIs, and with Swagger UI it provides online sandbox for frontend developers.
provides Swagger support for Spring based REST APIs.
Add springfox to dependencies.
io.springfoxspringfox-swagger2${springfox.version}
io.springfoxspringfox-swagger-ui${springfox.version}
springfox-swagger-ui
provides static Javascript UI for visualizing the Swagger schema definitions.
Add a @Configuration
class to enable Swagger.
When the application starts up, it will scan all Controllers and generate Swagger schema definition at runtime, Swagger UI will read definitions and render user friendly UI for REST APIs.
View REST APIs in swagger ui.
Starts up this application via command line.
Open browser and navigate .
You will see the screen like the following.
The Swagger schema definition generation will consume lots of system resourcs at runtime.
Add swagger2-markup-maven-plugin
into pom.xml file.
io.github.swagger2markupswagger2markup-maven-plugin${swagger2markup.version}io.github.swagger2markupswagger2markup-import-files-ext${swagger2markup.version}io.github.swagger2markupswagger2markup-spring-restdocs-ext${swagger2markup.version}${swagger.input}${generated.asciidoc.directory}ASCIIDOCTAGS${project.basedir}/src/docs/asciidoc/extensions/overview${project.basedir}/src/docs/asciidoc/extensions/definitions${project.basedir}/src/docs/asciidoc/extensions/paths${project.basedir}src/docs/asciidoc/extensions/security/${swagger.snippetOutput.dir}truetestconvertSwagger2markup
The convertSwagger2markup
goal will convert Swagger schema definition into asciidocs.
Add asciidoctor-maven-plugin
into pom.xml
file.
org.asciidoctorasciidoctor-maven-plugin1.5.3org.jrubyjruby-complete${jruby.version}org.asciidoctorasciidoctorj-pdf${asciidoctorj-pdf.version}${asciidoctor.input.directory}index.adoccoderaybookleft3${generated.asciidoc.directory}output-htmltestprocess-asciidochtml5${asciidoctor.html.output.directory}output-pdftestprocess-asciidocpdf${asciidoctor.pdf.output.directory}
asciidoctor-maven-plugin
will generate the asciidocs into HTML5 and PDF files.
Add spring-restdocs
support.
spring-restdocs
will generate the sample code snippets from test, which can be combined into the final docs.
Add related dependencies into pom.xml
file.
io.github.swagger2markupswagger2markup-spring-restdocs-ext${swagger2markup.version}test
org.springframework.restdocsspring-restdocs-mockmvctest
Write test codes to generate sample code snippets.
Run mvn clean verify
to execute all tests and generate HTML5 and PDF file for the REST APIs.
Open \target\asciidoc\html\index.html in browser, it looks like.
Open \target\asciidoc\pdf\index.pdf in Pdf viewer, it looks like.
Check out sample codes from my github account.
Or the Spring Boot version:
In the above steps, the Swagger schema definition is generated at runtime, you can get the content via link:. You will see the complete Swagger schema definition.
You can save this page content as a json file and upload to and edit it online.
Combined with Springfox, , and , the Swagger schema definition can be converted to asciidocs, and with asciidoctor-maven-plugin
, the asciidocs can be generated into static HTML5 or PDF files.
Read the live version of theses posts from Gitbook:.