DevOps Friendly Doc Publishing for APIs & Microservices

Microservices create an explosion of internal and external APIs. These APIs need great docs. Many organizations end up with a jungle of wiki pages, swagger docs and API consoles. Keeping docs updated …

Microservices create an explosion of internal and external APIs. These APIs need great docs. Many organizations end up with a jungle of wiki pages, swagger docs and API consoles. Keeping docs updated and in sync with code can be a challenge. We’ve been working on a project to help solve this problem for engineering teams internally across Cisco. The goal is to create a forward looking developer and API doc publishing pipeline that: - Has a developer friendly editing flow - Accepts many API spec formats (Swagger, RAML, etc) - Supports long form documentation in markdown - Is CI/CD pipeline friendly so that code and docs stay in sync - Is flexible enough to be used by a wide scope of teams and technologies This session will share many lessons learned about tooling and attendees will learn how to solve documentation challenges for internal and external facing APIs. We have found that solving this doc publishing flow is a key component of a building modern infrastructure.