# How we validate our API documentation and specs
source: https://developer.mastercard.com/blog/validate-api-docs/index.md

Authors: Hyunjoe Yoo. This post will cover how we automate the validation of API documentation, which is an ongoing project developed by our API Consultancy and Standards team (API C\&S team). The API C\&S team is responsible for the quality of the APIs published on the Mastercard Developer platform. They provide the processes and tooling to enable the API service teams to review their API specifications, technical documentation, and reference apps. Every new and updated API specification and related technical documentation needs to be validated. For security reasons, we can't use external tools like Grammarly, as we are prohibited from transferring the data to an external site. Moreover, there was a challenge of integrating external tools with internal pipelines for automation. A quick note about our content management and publishing platform. We were inspired by JAMstack, a term coined by Mathias Biilmann which he defines as "JavaScript, APIs, and prerendered Markup". The idea is that we can create websites using a markup format like Markdown to generate a static page, then combine it with JavaScript and APIs to render in the browser. It simplifies content management tremendously because we don't have to build and maintain a user interface for content creation, database to store it or back-end servers to retrieve it. We have another blog that goes into more detail about how we use JAMstack here. With JAMstack architecture, our technical writers can get their jobs done more efficiently by focusing on the content -- not the CMS, and they can all work at the same time in a distributed fashion. Most importantly, they can write docs like code because Markdown is a plaintext format suitable for version control systems like Git. It is practically a type of source code for content. If you want to read more about the advantages of treating documentation like code, you can check out the related blog here. So, by treating our documentation as code, we could tap into the same build pipelines that our code build and deployments use to generate, validate, and publish the content. We added a Python 3 module to the pipeline which we called the JAMstack Content Checker. It checks the content by pulling down the repository contents from Git, parsing the Markdown files into the published text and then validating for spelling mistakes, banned phrases, technical or business jargon phrases, missing content sections, and broken links. Diving into each stage, the spell checker utilizes a list of 466K English words from an open source dictionary as a base. This is a flat text file and we manually added some terms specific to our business and financial domain. The Python script cleans out the Markdown (through simple regular expressions), tokenizes the remaining text and removes duplicates. It then checks these against the dictionary to detect spelling mistakes through the content before it gets published. The banned phrases script ensures that our internal terminology (like internal project names and acronyms) doesn't get exposed externally. It is a flat file (just like the English words dictionary mentioned above) that we have manually updated. It also includes commonly misspelled brand names as well as incorrect use of upper case e.g. catching any legacy "MasterCard" when it should be "Mastercard". Mmm, now that last sentence is going to trigger the script every time :) We defined the dictionary for internal words ourselves, which came from our own domain experience by reviewing hundreds of pages of content. We also include a mapping to the correct replacement word. The Markdown Quality Checker script detects missing sections, JAMstack miss-configurations and the quality of the Markdown. We scan the Front Matter element names for missing mandatory sections and validate that the configuration values adhere to our rules. Finally, it looks for the most common mistakes we see content editors making e.g. leaving behind a TODO comment. Lastly, the script checks every internal and external link to detect broken links or links to lower environments that should have been replaced. We locate all the links, pull them into an array and ping each one in turn using the Python Request Library to check for a 200 response. This modular approach with each step implemented by it's own Python script allowed us to extend it further to add in our latest module which pulls down the Open API spec file from Git, spell check the descriptions and element names. All of the issues are output to a PDF report using the Reportlab.com library. The report includes line numbers along with the issue which makes it easy for the author to edit the original files.