Posts

Showing posts from January, 2017

Using Spring REST docs to document a public API

Image
During my talks last year about Spring REST docs, I was frequently asked if I could use Spring REST docs to document other APIs. I always thought it was possible, but now I have a working example.  I was able to configure RestAssured to poll a public demo API,  JSON Placeholder, and use those snippets to form API docs.

The demo repository is available at https://github.com/jlstrater/spring-boot-restdocs-public-api-example, and the docs are published at https://jlstrater.github.io/spring-restdocs-public-api-example

The rest of the example is similar to any other Spring REST Docs example, but the configuration is slightly different:


In figure 1, the third line specifies the URL to run against.  This will also affect the generated snippets as seen in Figure 2. This shows how it will use the real address instead of localhost like it would for a local example.


Conclusion
This could be useful for documenting parts of a system, you may not have direct access to, or for highly complex systems …