Showing posts from January, 2017

Using Spring REST docs to document a public API

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, and the docs are published at

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.

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