{"id":39113,"date":"2019-09-12T09:54:20","date_gmt":"2019-09-12T09:54:20","guid":{"rendered":"https:\/\/developers.messagemedia.com\/?p=2184"},"modified":"2019-09-12T09:54:20","modified_gmt":"2019-09-12T09:54:20","slug":"managing-api-documentation-over-multiple-teams","status":"publish","type":"blog","link":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/","title":{"rendered":"Managing API documentation over multiple teams"},"content":{"rendered":"

In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation. At MessageMedia, some of our APIs have had multiple developers involved in the creation of the documentation<\/a>\u00a0before it becomes public-facing, at which point the Developer Relations team is responsible for making it ready for your consumption. We also have APIs that are used internally as well as externally. Keeping our public-facing documentation up to date is something we\u2019re working on improving at MessageMedia.\u00a0<\/span><\/p>\n

API Blueprints<\/span><\/h2>\n

API Blueprint is a high-level API description language. It\u2019s an alternative to OpenAPI specifications (also known as Swagger). API Blueprint can be preferable in some circumstances because it is known for being easier to read for members of the team who don\u2019t spend all day \u2018down in the weeds\u2019 of the code. An .apib file is essentially a markdown format file and its look and feel is familiar to anyone who has edited a Github readme file before. It\u2019s easy for a community manager or a product manager to\u00a0 change a description or add things with confidence that they\u2019re not going to \u2018break\u2019 the way something renders. Some of the disadvantages of using .apib are that it lacks the same ecosystem around code level tooling that Swagger has. For example, Swagger code-gen is a huge time-saver for generating SDKs directly from a Swagger specification. I\u2019m in the process of working around this but for now, we\u2019re \u2018all in\u2019 on API Blueprint at MessageMedia.\u00a0<\/span><\/p>\n

Including markdown templates<\/span><\/h2>\n

Aglio is an API Blueprint renderer that outputs static HTML, similar to Swagger UI for Swagger specs, or any of the other OpenAPI spec renderers. Aglio has several benefits for .apib users, including multiple themes and customisable output. However, the feature that really appealed to us, in this case, was the ability use \u2018includes\u2019. An ‘include’ is a separate markdown document nested in your API spec project that can be \u201cpulled in\u201d to the final render, and used in other neighbouring renders. This means that we can, for example, include the main body of the reporting documentation<\/a> from the reporting team, include another team’s authentication information, and include any other surrounding information like a Postman collection button. In this scenario, Aglio will spit out a complete public-facing .abib file.<\/span><\/p>\n

\"\"<\/p>\n

<\/h2>\n

<\/h2>\n

<\/h2>\n

<\/h2>\n

<\/h2>\n

<\/h2>\n

Distributing across teams<\/span><\/h2>\n

Now that we understand the concept of how Aglio can generate from multiple sources, the second issue is how to get sources from multiple git repos in the right place. The reporting team has its, Developer Relations has a public-facing documentation repo, and we need to be able to reference the master version of their repo so that changes get pulled in as they occur. The answer to this problem is submodules.\u00a0<\/span><\/p>\n

Sub moduling is a git feature that allows you to <\/span>use another project from within your project. It’s similar to including a package via a package manager. You can read more about the feature and its usage <\/span>here<\/span><\/a>, but to get started quickly, follow these instructions:\u00a0<\/span><\/p>\n

Step 1: <\/b>Add the submodule<\/span><\/p>\n

git submodule add git:\/\/github.com\/coder_bec\/docsmaster.git docs<\/span><\/pre>\n
Step 2: <\/b>Fix the submodule to a particular branch (devrel branch)<\/span><\/p>\n
git checkout -b dev_branch origin\/dev_branch<\/span><\/pre>\n
Step 3: <\/b>Commit everything<\/span><\/p>\n
git add .\n\ngit commit -m 'adding submodules'<\/pre>\n
Now, whenever the reporting team does an update to their repo, they do a PR to our branch \u2013 can we add this as a pipeline? – maybe.<\/span><\/p>\n
Now when a change is made to a downstream submodule, you fetch and merge it.\u00a0<\/span><\/p>\n
Step 4:<\/strong> Fetch and merge<\/span><\/p>\n
git fetch<\/span>\n\ngit merge origin\/master<\/span><\/pre>\n
\"\"<\/p>\n
The question then becomes how to make sure you know when to fetch and merge and push your new docs. For now, we have a notification on the bitbucket repo that tells us when to do this. In the future we could look at ways to automate this. Let us know on our\u00a0Developer Slack<\/a>\u00a0if you have any suggestions!<\/span><\/p>\n
Putting it all together with Buildkite<\/span><\/h2>\n
Now that we\u2019ve got our new process and it\u2019s pulling in from all the right places, we can make a Buildkite pipeline that does a bunch of stuff and deploys our .apib file to our Apiary account.\u00a0<\/span><\/p>\n
\"\"<\/p>\n
In the pipeline file above, we lint the documentation, validate it with a file that checks it’s a proper .apid file, then publish it to our Apiary account.<\/p>\n
The future<\/span><\/h2>\n
In the future, we will look at using the HTML rendering features of Aglio and moving outside of Apiary. We may also be looking at ways to automate this process.<\/span><\/p>\n","protected":false},"author":0,"featured_media":8909,"menu_order":170,"template":"page-blog-v2.php","meta":{"_acf_changed":false,"popular":false,"coming_soon":false,"link":"","footnotes":""},"blog_category":[37],"class_list":["post-39113","blog","type-blog","status-publish","has-post-thumbnail","hentry","blog_category-developers"],"acf":[],"yoast_head":"\nManaging API documentation over multiple teams - Sinch MessageMedia Australia<\/title>\n<meta name=\"description\" content=\"In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation. Australia\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Managing API documentation over multiple teams - Sinch MessageMedia\" \/>\n<meta property=\"og:description\" content=\"In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/\" \/>\n<meta property=\"og:site_name\" content=\"Sinch MessageMedia\" \/>\n<meta property=\"og:image\" content=\"https:\/\/messagemedia.com\/wp-content\/uploads\/2019\/09\/Managing-API-documentation-over-multiple-teams.png\" \/>\n\t<meta property=\"og:image:width\" content=\"919\" \/>\n\t<meta property=\"og:image:height\" content=\"290\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/\",\"url\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/\",\"name\":\"Managing API documentation over multiple teams - Sinch MessageMedia\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/messagemedia.com\\\/wp-content\\\/uploads\\\/2019\\\/09\\\/Managing-API-documentation-over-multiple-teams.png\",\"datePublished\":\"2019-09-12T09:54:20+00:00\",\"description\":\"In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/#breadcrumb\"},\"inLanguage\":\"en-AU\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-AU\",\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/#primaryimage\",\"url\":\"https:\\\/\\\/messagemedia.com\\\/wp-content\\\/uploads\\\/2019\\\/09\\\/Managing-API-documentation-over-multiple-teams.png\",\"contentUrl\":\"https:\\\/\\\/messagemedia.com\\\/wp-content\\\/uploads\\\/2019\\\/09\\\/Managing-API-documentation-over-multiple-teams.png\",\"width\":919,\"height\":290,\"caption\":\"Managing API documentation over multiple teams\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/blog\\\/managing-api-documentation-over-multiple-teams\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Blog\",\"item\":\"https:\\\/\\\/messagemedia.com\\\/us\\\/blog\\\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Managing API documentation over multiple teams\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/#website\",\"url\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/\",\"name\":\"Sinch MessageMedia\",\"description\":\"Business SMS & Messaging Platform\",\"publisher\":{\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-AU\"},{\"@type\":\"Organization\",\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/#organization\",\"name\":\"Sinch MessageMedia\",\"url\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-AU\",\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/#\\\/schema\\\/logo\\\/image\\\/\",\"url\":\"https:\\\/\\\/messagemedia.com\\\/wp-content\\\/uploads\\\/2024\\\/03\\\/logo-mm-sinch.svg\",\"contentUrl\":\"https:\\\/\\\/messagemedia.com\\\/wp-content\\\/uploads\\\/2024\\\/03\\\/logo-mm-sinch.svg\",\"width\":1,\"height\":1,\"caption\":\"Sinch MessageMedia\"},\"image\":{\"@id\":\"https:\\\/\\\/messagemedia.com\\\/au\\\/#\\\/schema\\\/logo\\\/image\\\/\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Managing API documentation over multiple teams - Sinch MessageMedia Australia","description":"In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation. Australia","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/","og_locale":"en_US","og_type":"article","og_title":"Managing API documentation over multiple teams - Sinch MessageMedia","og_description":"In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation.","og_url":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/","og_site_name":"Sinch MessageMedia","og_image":[{"width":919,"height":290,"url":"https:\/\/messagemedia.com\/wp-content\/uploads\/2019\/09\/Managing-API-documentation-over-multiple-teams.png","type":"image\/png"}],"twitter_card":"summary_large_image","schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/","url":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/","name":"Managing API documentation over multiple teams - Sinch MessageMedia","isPartOf":{"@id":"https:\/\/messagemedia.com\/au\/#website"},"primaryImageOfPage":{"@id":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/#primaryimage"},"image":{"@id":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/#primaryimage"},"thumbnailUrl":"https:\/\/messagemedia.com\/wp-content\/uploads\/2019\/09\/Managing-API-documentation-over-multiple-teams.png","datePublished":"2019-09-12T09:54:20+00:00","description":"In organisations that produce SaaS products with public APIs, there is sometimes complex interplay between who is responsible for what ultimately becomes public-facing API documentation.","breadcrumb":{"@id":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/#breadcrumb"},"inLanguage":"en-AU","potentialAction":[{"@type":"ReadAction","target":["https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/"]}]},{"@type":"ImageObject","inLanguage":"en-AU","@id":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/#primaryimage","url":"https:\/\/messagemedia.com\/wp-content\/uploads\/2019\/09\/Managing-API-documentation-over-multiple-teams.png","contentUrl":"https:\/\/messagemedia.com\/wp-content\/uploads\/2019\/09\/Managing-API-documentation-over-multiple-teams.png","width":919,"height":290,"caption":"Managing API documentation over multiple teams"},{"@type":"BreadcrumbList","@id":"https:\/\/messagemedia.com\/au\/blog\/managing-api-documentation-over-multiple-teams\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/messagemedia.com\/au\/"},{"@type":"ListItem","position":2,"name":"Blog","item":"https:\/\/messagemedia.com\/us\/blog\/"},{"@type":"ListItem","position":3,"name":"Managing API documentation over multiple teams"}]},{"@type":"WebSite","@id":"https:\/\/messagemedia.com\/au\/#website","url":"https:\/\/messagemedia.com\/au\/","name":"Sinch MessageMedia","description":"Business SMS & Messaging Platform","publisher":{"@id":"https:\/\/messagemedia.com\/au\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/messagemedia.com\/au\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-AU"},{"@type":"Organization","@id":"https:\/\/messagemedia.com\/au\/#organization","name":"Sinch MessageMedia","url":"https:\/\/messagemedia.com\/au\/","logo":{"@type":"ImageObject","inLanguage":"en-AU","@id":"https:\/\/messagemedia.com\/au\/#\/schema\/logo\/image\/","url":"https:\/\/messagemedia.com\/wp-content\/uploads\/2024\/03\/logo-mm-sinch.svg","contentUrl":"https:\/\/messagemedia.com\/wp-content\/uploads\/2024\/03\/logo-mm-sinch.svg","width":1,"height":1,"caption":"Sinch MessageMedia"},"image":{"@id":"https:\/\/messagemedia.com\/au\/#\/schema\/logo\/image\/"}}]}},"_links":{"self":[{"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/blog\/39113","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/blog"}],"about":[{"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/types\/blog"}],"version-history":[{"count":0,"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/blog\/39113\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/media\/8909"}],"wp:attachment":[{"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/media?parent=39113"}],"wp:term":[{"taxonomy":"blog_category","embeddable":true,"href":"https:\/\/messagemedia.com\/au\/wp-json\/wp\/v2\/blog_category?post=39113"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}