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 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.
This could be useful for documenting parts of a system, you may not have direct access to, or for highly complex systems where responses are proxied through gateways. One problem I experienced in a project was that the documentation was valid for requests run against that service directly, but was not indicative of for how external developers would access the service through our API Gateway. With this tactic, documentation could be built around the gateway instead of the service itself. This could also be utilized to code the host URL for each environment. It should be noted that this tactic will only work for RestAssured and not MockMVC.
If you want to learn more about Spring REST docs, you can come see me next week at JFokus or look at the resources below.
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:
 |
| Figure 1: RestAssured Configuration |
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.
 |
| Figure 2: Example Snippet with JSON Placeholder Address |
Conclusion
This could be useful for documenting parts of a system, you may not have direct access to, or for highly complex systems where responses are proxied through gateways. One problem I experienced in a project was that the documentation was valid for requests run against that service directly, but was not indicative of for how external developers would access the service through our API Gateway. With this tactic, documentation could be built around the gateway instead of the service itself. This could also be utilized to code the host URL for each environment. It should be noted that this tactic will only work for RestAssured and not MockMVC.If you want to learn more about Spring REST docs, you can come see me next week at JFokus or look at the resources below.
Comments
Post a Comment