Supports most REST API description formats (OpenAPI, RAML, API Blueprint, etc.) and provides SDK code generation, conversions from one spec format to another, and many more services. APIMATIC “lets you define APIs and generate SDKs for more than 10 languages.” For example, you can automatically convert Swagger 2.0 to 3.0 using the API Transformer service on this site. See https://apimatic.io/ and read the documentation.
A cross-platform service provided by APIMATIC that will automatically convert your specification file from one format or version to another. See apimatic.io/transformer.
Platform that supports the full life-cycle of API design, development, and deployment. For interactive documentation, Apiary supports the API Blueprint specification, which similar to OpenAPI or RAML but includes more Markdown elements. See apiary.io.
The API Blueprint spec is an alternative to OpenAPI or RAML. API Blueprint is written in a Markdown-flavored syntax. See API Blueprint in this book, or go to API Blueprint’s homepage to learn more.
Similar to Apiary, Apigee provides services for you to manage the whole lifecycle of your API. Specifically, Apigee lets you “manage API complexity and risk in a multi- and hybrid-cloud world by ensuring security, visibility, and performance across the entire API landscape.” Supports the OpenAPI spec. See apigee.com.
In Git, a branch is a copy of the repository that is often used for developing new features. Usually you work in branches and then merge the branch into the master branch when you’re ready to publish. If you’re editing documentation in a code repository, developers will probably have you work in a branch to make your edits. The developers will then either merge the branch into the master when ready, or you might submit a pull request to merge your branch into the master. See git-branch.
In Git, a clone is a copy of the repository. The first step in working with any repository is to clone the repo locally. Git is a distributed version control system, so everyone working in it has a local copy (clone) on their machines. The central repository is referred to as the origin. Each user can pull updates from origin and push updates to origin. See git-clone.
Refers to the Swagger tooling integrated with code libraries to auto-generate the Swagger specification file from annotations in the code. “Swagger Codegen can simplify your build process by generating server stubs and client SDKs from your Swagger specification.” See Swagger Codegen.
In Git, a commit is when you take a snapshot of your changes to the repo. Git saves the commit as a snapshot in time that you can revert back to later if needed. You commit your changes before pulling from origin or before merging your branch within another branch. See git-commit.
Create, Read, Update, Delete. These four programming operations are often compared to POST, GET, PUT, and DELETE with REST API operations.
A command line utility often used to interact with REST API endpoints. Used in documentation for request code samples. curl is usually the default format used to display requests in API documentation. See curl. Also written as cURL. See Make a cURL call and Understand cURL more.
Distributed version control system commonly used when interacting with code. GitHub uses Git, as does BitBucket and other version control platforms. Learning Git is essential for working with developer documentation, since this is the most common way developers share, review, collaborate, and distribute code. See https://git-scm.com/.
A platform for managing Git repositories. Used for most open source projects. You can also publish documentation using GitHub, either by simply uploading your non-binary text files to the repo, or by auto-building your Jekyll site with GitHub Pages, or by using the built-in GitHub wiki. See GitHub wikis in this book as well as Github.com.
A tool for consolidating and managing many smaller repos with one system. See git-repo.
Help Authoring Tool. Refers to the traditional help authoring tools (RoboHelp, Flare, Author-it, etc.) used by technical writers for documentation. Tooling for API docs tend to use Docs as code tools more than HATs.
Stands for Hypermedia as the Engine of Application State. Hypermedia is one of the characteristics of REST that is often overlooked or missing from REST APIs. In API responses, responses that span multiple pages should provide links for users to page to the other items. See HATEOS.
A static site generator that uses the Go programming language as its base. Along with Jekyll, Hugo is among the top 5 most popular static site generators. Hugo is probably the fastest site generator available. Speed matters as you scale the number of documents in your project beyond several hundred. See https://gohugo.io/.
Similar to Apiary or Apigee, Mulesoft provides an end-to-end platform for designing, developing, and distributing your APIs. For documentation, Mulesoft supports RAML. See https://www.mulesoft.com/.
The official name for the Swagger specification. The OpenAPI specification provides a set of elements that can be used to describe your REST API. When valid, the specification file can be used to create interactive documentation, generate client SDKs, run unit tests, and more. See https://github.com/OAI/OpenAPI-Specification. Now under the Open API Initiative with the Linux Foundation, the OpenAPI specification aims to be vendor neutral.
Revision control system often used before Git became popular. Often configured as centralized repository instead of a distributed repository. See Perforce.
In Git, when you pull from origin, you get the latest updates from origin onto your local system. When you run git pull, Git tries to automatically merge the updates from origin into your own copy. If the merge cannot happen automatically, you might see merge conflicts. See https://git-scm.com/docs/git-pull.
A request from an outside contributor to merge a cloned branch back into the master branch. The pull request workflow is commonly used with open source projects, because developers outside the team will not usually have contributor rights to merge updates into the repository. GitHub has a great interface for making and processing pull requests. See Pull Requests.
In Git, when you want to update the origin with the latest updates from your local copy, you make git push. Your updates will bring origin back into sync with your local copy. See https://git-scm.com/docs/git-push.
Stands REST API Modeling Language and is similar to Swagger and other API specifications. RAML is backed by Mulesoft, a commercial API company, and uses a more YAML-based syntax in the specification.See RAML tutorial in this book or RAML.
In Mulesoft, the RAML Console is where you design your RAML spec. Similar to the Swagger Editor for the OpenAPI spec.
In Git, a repo (short for repository) stores your project’s code. Usually you only store non-binary (human-readable) text files in a repo, because Git can run diffs on text files and show you what has changed (but not with binary files).
Stands for Representational State Transfer. Uses web protocols (HTTP) to make requests and provide responses in a language agnostic way, meaning that users can choose whatever programming language they want to make the calls. See What is a REST API?.
The company that maintains and develops the open source Swagger tooling (Swagger Editor, Swagger UI, Swagger Codegen, and others), and which that formed the OpenAPI Initiative which leads the evolution of the Swagger (OpenAPI) specification. Also developed SwaggerHub. See Smarbear.
A static site generator developed for managing documentation for Python. Sphinx is the most documentation-oriented static site generator available and includes many robust features – such as search, sidebar navigation, semantic markup, managed links – that other static site generators lack. Based on Python. See https://www.staticgen.com/sphinx.
Static site generator
A breed of website compilers that package up a group of files (usually written in Markdown) and make them into a website. There are more than 350 different static site generators. See Jekyll in this book for a deep-dive into the most popular static site generator, or Staticgen for a list of all static site generators.
An official specification for REST APIs. Provides objects used to describe your endpoints, parameters, responses, and security. Now called OpenAPI specification.
The specification file, usually created manually, that defines the blueprints that developers should code the API to. The contract aligns with a “spec-first” or “spec-driven development” philosophy. The contract essentially acts like the API requirements for developers. See this blog post/podcast for details.
Swagger specification validator. An online editor that dynamically checks whether your Swagger specification file is valid.
Swagger specification file
The file (either in YAML or JSON syntax) that describes your REST API. Follows the OpenAPI specification format.
A display framework. The most common way to parse a Swagger specification file and produce the interactive documentation as shown in the Petstore demo.
A site developed by Smartbear to help teams collaborate around the Swagger spec. In addition to generating interactive documentation from SwaggerHub, you can generate many client and server SDKs and other services. See Manage Swagger Projects with SwaggerHub.
Stands for version control system. Git and Mercurial are examples.
A system for managing code that relies on snapshots that store content at specific states. Enables you to revert to previous states, branch the code into different versions, and more. See About Version Control for details.
Recursive acronym for “YAML Ain’t No Markup Language.” A human- readable, space-sensitive syntax used in the Swagger specification file. See More About YAML.