I have been talking with Nick Houghton over at Sandbox about the state of OpenAPI Spec driven API documentation, and the lack of a machine-readable core when you deployed Slate driven documentation. He was wanting the same thing--a good looking, dynamic API documentation that was OpenAPI Spec driven.
He recently got back to me and found a solution that worked for them: "Ended up just templating the Swagger JSON myself rather than relying on Slate etc to do it. So model/resources are Swagger annotated, CI pushes out Swagger JSON and Angular UI parses in the browser, works quite well I think".
Nick is on a similar path that I am, as I work to simply API documentation using OpenAPI Spec, and provide specialized views of APIs using Liquid. We are looking for the simplicity, control, and beauty of Slate, but the machine readable core of OpenAPI Spec--allowing us to keep the core specification for the API up to date, and the documentation is always the latest.
They are going to write up their journey on their blog (as all API service providers should), and share with us. I'll probably do another write-up once I get more details on how they created the templated API docs using OpenAPI Spec and Angular. I also like how they have the OpenAPI Spec JSON pushed out as part of the CI life-cycle--something I'll cover more as part of my API life-cycle orchestration research.
