In 2016, I migrated the API and front-end documentation of an e-commerce platform from Contentful to Slate as my first solo (and major) ruby projec...
For further actions, you may consider blocking this person and/or reporting abuse
Hello Alyss. Thank you for this blog post, it was really helpful. I have very recently started documenting APIs and am also using slate for the document. One problem I am having is that I need the option API testing like in Swagger, but I can't find any option for that through slate. Is there a way I can get the API testing in slate or is there any other tool which offers the ease of slate with API testing?
So you are using swagger for documentation or looking for a solution like swagger?
I'm looking for a solution like swagger but with better UI. I need an interface that I can change and edit to my own liking.
If you haven't seen it already, check out postman's solution. They have the ability to do contract testing for APIs as well.
Thanks Alyss. We checked out postman but it is a paid solution. We cannot go for any paid solution right now. Is there any open source tool we can use?
If you need contract testing, I don't have any recommendations I could give that I've also tested.
is there a way to export from postman and import to slate?
Are you exporting the postman docs or the api request collection?
for now i'd be happy with documentation only
Sorry, I was trying to clarify what file type you'd be working with. Is there a way to export existing markdown files or swagger/OAS from postman and is that what you'll be using?
Ok, my attempt is to use Postman for debugging and writing the doc. But Slate to publish. So I'd need postman to export a json that I can somehow convert for Slate
Depending on the file output, you might have an easier time with a project that could just consume open api spec out of the box. Box custom built their dev docs and pull from their open api spec repository. You can see some code here but I don't believe an arch diagram has been published github.com/box/developer.box.com
Hi we are evaluating Slate for API documentation. We also have swagger yaml spec. I have seen some solutions for swagger yaml to slate markdown conversion, but that seems like having all documentarion in yaml and use slate for rendering. What I want ideally is have swagger yaml as baseline API doc that comes with dev release and be able to build more detailed documentation on top of it directly in slate. Key here is to be able to preserve both slate doc & baseline doc from swagger every release without having to redo slate documentation. Have you come across this workflow or have any tips? Thanks
There's only one or two options that come to mind that might work, but I haven't personally tried to tackle this problem.
If you look at how Slate handles the TOC, there's a file in the ~/lib subdirectory that does a pre-rendering of the content. So the markdown has already been covered to html and this modifies it. You might be able to get away with something similar if the swagger converted file and the baseline doc had something you could consistently match up against, like a header. The main issue with that is you may have a superfluous site path unless you buried one of the markdown files outside of the normal directory.
Alternatively, you could modify deploy.sh to use regex to merge the two files so they maintain separation in your code base until they are ready to go live. That way you have a single URL path and the documentation would use the normal middleman rendering path. Any changes to ~/deploy.sh would need to come before the run_build() function.
All of that is speculation on what might work. I haven't touched Slate in sometime, but hopefully it can get you in the right direction.