{"id":2729,"date":"2020-07-07T13:00:00","date_gmt":"2020-07-07T13:00:00","guid":{"rendered":"https:\/\/readmeprd.wpenginepowered.com\/?p=1920"},"modified":"2025-12-16T19:40:38","modified_gmt":"2025-12-17T01:40:38","slug":"how-to-use-openapi-and-swagger-spec-for-documentation","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation","title":{"rendered":"How to Use OpenAPI and Swagger for Documentation"},"content":{"rendered":"\n<p>Excellent API documentation experiences stem from proper use of an OpenAPI or Swagger API description file. In this guide, we explain Swagger and OpenAPI, how to create an OpenAPI or Swagger description for an API, and how to use the OpenAPI Specification to yield documentation that\u2019s continuously up-to-date and automated!<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/owlbert-hiking-banner.png\" alt=\"Owlbert with a hiking map\"\/><\/figure>\n\n\n\n<p>HTTP API descriptions, like those described in the <a href=\"https:\/\/github.com\/OAI\/OpenAPI-Specification\">OpenAPI Specification<\/a>, end up being helpful in a variety of ways for your development teams, but also your broader users.<\/p>\n\n\n\n<p>The challenge: Manually creating comprehensive and accurate documentation is difficult. It\u2019s a chore to produce, especially when it exists as a task to be done separate from the original code creation. API documentation is easily neglected and becomes outdated. New endpoints go undocumented, which unfortunately means they will never exist in the minds of most developers. Even worse, if API response data changes, there\u2019s no way for developers to learn what to expect from each request.<\/p>\n\n\n\n<p>A developer\u2019s experience with an unfamiliar API is dictated by its documentation. The API\u2019s reference guide provides the first impression of quality and consistency. The reference guide is the source of truth that developers return to whenever there\u2019s a serious issue or question about an API\u2019s functioning, and therefore must be painstakingly managed.<\/p>\n\n\n\n<p>Enter: Swagger and OpenAPI.<\/p>\n\n\n\n<p>Swagger and OpenAPI are specifications to describe HTTP APIs (the most common type of API). These machine-readable formats define everything a developer needs to integrate with an API: authentication, endpoints, HTTP methods, request data, response fields, and detailed error codes. They\u2019re easy to create and can be used in many forms of automation. We\u2019ll explore the ways to use OpenAPI and Swagger in the remainder of this guide.<\/p>\n\n\n\n<p>Key advantages of API description formats like Swagger and OpenAPI include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Easier documentation management, comprehensive by nature<\/li>\n\n\n\n<li>Allow automated testing for API validity<\/li>\n\n\n\n<li>Easier sharing and publication of API specifications<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"openapi-common-terms-and-definitions\">OpenAPI common terms and definitions<\/h2>\n\n\n\n<p>If you&#8217;re new to this topic you\u2019ll see many unfamiliar terms used throughout this guide and on the web as you research Swagger and OpenAPI specifications. We\u2019ve gathered the essential definitions in this brief glossary so you can reference your knowledge before you begin.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Definition<\/strong>: The document, in either Swagger or OpenAPI format, that defines a specific API.<\/li>\n\n\n\n<li><strong>Description<\/strong>: Another term for an API definition, which describes a specific API.<\/li>\n\n\n\n<li><strong>Documentation<\/strong>: The human-readable API reference, getting started guides, tutorials, and any other content used to introduce an API to a developer.<\/li>\n\n\n\n<li><strong>OAS<\/strong>: OpenAPI Specification. (See OpenAPI.)<\/li>\n\n\n\n<li><strong>OpenAPI<\/strong>: A specification which declares a syntax for the human and machine-readable API descriptions.<\/li>\n\n\n\n<li><strong>OpenAPI document<\/strong>: Another term for the OpenAPI flavor of API definition.<\/li>\n\n\n\n<li><strong>OpenAPI file<\/strong>: An individual OpenAPI document.<\/li>\n\n\n\n<li><strong>OpenAPI Initiative<\/strong>: The industry-wide working group that maintains the OpenAPI format.<\/li>\n\n\n\n<li><strong>Specification<\/strong>: A set of rules that defines the format for OpenAPI and Swagger.<\/li>\n\n\n\n<li><strong>Swagger<\/strong>: The original API description format, which later became OpenAPI. Also, SmartBear\u2019s line of tools to interact with Swagger and OpenAPI files.<\/li>\n\n\n\n<li><strong>Swagger file<\/strong>: Another term for the Swagger flavor of API definition.<\/li>\n\n\n\n<li><strong>Version 2<\/strong>: The shorthand for Swagger 2.0 and OpenAPI 2.0, which are two names for the same specification format.<\/li>\n\n\n\n<li><strong>Version 3<\/strong>: The shorthand for OpenAPI 3.0 (and more recent minor versions), the most recent OpenAPI specification.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">What are Swagger and OpenAPI?<a id=\"whatareswaggerandopenapi\"><\/a><\/h2>\n\n\n\n<p>Swagger and OpenAPI are API description formats that provide a common framework for teams to build and document APIs. These machine-readable definitions open up many opportunities at each stage of the API lifecycle.<\/p>\n\n\n\n<p>A <a href=\"https:\/\/readme.com\/resources\/what-is-swagger-and-why-it-matters\">Swagger  document describes your APIs<\/a> so you can keep them documented, test their validity, and share the expected results within your company and beyond.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">OpenAPI for documentation (and more)<\/h2>\n\n\n\n<p>The biggest API headache developers cite is inaccurate and outdated documentation (2019 <a href=\"https:\/\/www.postman.com\/resources\/infographics\/api-survey-2019\/\">Postman API survey<\/a>). It is difficult, sometimes impossible, to integrate an API that is poorly documented. Unfortunately, many developers avoid writing documentation, or aren\u2019t comprehensive when they do so.<\/p>\n\n\n\n<blockquote class=\"wp-block-quote is-layout-flow wp-block-quote-is-layout-flow\">\n<p><strong>OpenAPI solves out-of-date documentation headaches by offering a standardized format that makes it easy to generate documentation that always matches the architecture of the API.<\/strong><\/p>\n<\/blockquote>\n\n\n\n<p>When an API changes, you can automatically generate rendered documentation based on the data contained in the underlying Swagger\/OAS API description. When documentation is in sync with your API description, developers won\u2019t worry about whether your documentation is accurate. Your developers can spend more time coding and less time documenting. Even better, since API descriptions are machine readable, you can make use of many automated tools.<\/p>\n\n\n\n<p>OpenAPI descriptions can be written in either YAML, or JSON. These notation formats were chosen because they are designed to be both easy for a human to read and write, and easy for software to parse.<\/p>\n\n\n\n<p>Here\u2019s an example API description in YAML format that describes a <a href=\"https:\/\/docs.readme.com\/developers\">ReadMe <\/a>GET operation to retrieve docs by their slug (name):<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"yaml\" class=\"language-yaml\">Paths:\n  \/docs\/{slug}:\n    get:\n      summary: Returns the doc with this slug\n      operationId: getDoc\n      parameters:\n        - name: slug\n          in: path\n          required: true\n          description: Slug of doc. must be lowercase, and replace spaces with hyphens.\n          type: string<\/code><\/pre>\n\n\n\n<p><em>A ReadMe API endpoint described in the YAML format<\/em><\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/lh4.googleusercontent.com\/liKvPGjRjASnpCxuoQa1LJEpkfl-GsAxK3yY_4Njm22AEda0VZ9cwHwRo47X_ZQMV8DgNBsA1_Fj5dXncHzz-1KX731j7DK8Jgco_dWR3HKIY7opRYdo0yvraaEPSKOyMS1x3aTI\" alt=\"ReadMe API endpoint rendered from YAML API description file into an interactive Reference Guide\"\/><figcaption class=\"wp-element-caption\"><span style=\"white-space: pre-wrap;\">ReadMe API endpoint rendered from YAML API description file into an interactive Reference Guide&nbsp;<\/span><\/figcaption><\/figure>\n\n\n\n<p>Documentation is the most visible output of OpenAPI and Swagger definitions, but there are many more applications. Engineers can use the same OpenAPI or Swagger file that generated the docs to set up continuous integration and other testing.<\/p>\n\n\n\n<p>As an API provider, imagine how great it feels to always know your documentation will match your API when you deploy! When you use an OpenAPI or Swagger definition, you can automatically generate documentation and check its validity as part of your deploy process.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"api-definitions-swagger-set-the-standard\">API definitions: Swagger set the standard<\/h2>\n\n\n\n<p>In the early 2010s, building APIs was like the Wild West. Most companies didn\u2019t have defined processes for how new APIs were added. Instead, each group or even individual engineers built them to their own specifications. They would produce whatever documentation they could, but often they were onto the next project. API documentation was often minimal, outdated, and missing important information needed to integrate. Over time, the API developer community realized a need to create standardized formats for describing APIs according to useful conventions.<\/p>\n\n\n\n<p>The industry arrived at an API definition workflow after years of developer frustration. Prior to Swagger, engineers attempted to cobble together tooling or, more likely, went without.<\/p>\n\n\n\n<figure class=\"wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio\"><div class=\"wp-block-embed__wrapper\">\n<div class=\"ratio ratio-16x9\"><iframe loading=\"lazy\" title=\"Tony Tam recounts the history of Swagger and the Open API Initiative\" width=\"800\" height=\"450\" src=\"https:\/\/www.youtube.com\/embed\/oxqZ9J6t420?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" allowfullscreen><\/iframe><\/div>\n<\/div><\/figure>\n\n\n\n<p>Other description formats coexist with Swagger, including API Blueprint and RAML, but Swagger succeeded by rallying a community behind it, including some early tooling. SmartBear Software acquired Swagger in 2015 and hired Tony Tam to lead a commercial product line around the format, establishing paid tools like SwaggerHub.<\/p>\n\n\n\n<p>The acquisition validated the importance of API descriptions, but at the time, it raised questions about whether the format would continue to be independent from the paid service provider.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"the-openapi-initiative-leads-the-way\">The OpenAPI initiative leads the way<\/h2>\n\n\n\n<p>After Swagger became the de facto standard for API definition, the industry recognized the need for a vendor-neutral option. In 2016, developer community leaders, including SmartBear, created the OpenAPI Initiative (<a href=\"https:\/\/www.openapis.org\/\">OAI<\/a>).<\/p>\n\n\n\n<p>Now part of the Linux Foundation, the OAI includes members from many large tech companies and API thought leaders.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/openapiinitiative-1.png\" alt=\"The OpenAPI Initiative logo\"\/><\/figure>\n\n\n\n<p>The OAI oversees the future of OpenAPI as a data format. A technical steering committee collaborates with the broader community to determine the vision for the format.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"swagger-vs-openapi-what%E2%80%99s-the-difference\">Swagger vs OpenAPI: What\u2019s the Difference?<\/h2>\n\n\n\n<p>The overlap between Swagger and OpenAPI Specification causes a lot of confusion. These are two separate, but very much related, specifications for describing APIs. SmartBear owns the Swagger name, but the current specification is now governed by the OAI.<\/p>\n\n\n\n<p>The last version of the Swagger data format was Swagger 2.0, released in 2014. SmartBear then donated the Swagger 2.0 specification to become the initial version of the OpenAPI specification (also designated 2.0).<\/p>\n\n\n\n<p>OpenAPI 3.0 was released in 2017 and is the current major version.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/openapi_version_table.png\" alt=\"Version table comparing different versions of OpenAPI\"\/><\/figure>\n\n\n\n<p>The initial version of OpenAPI is designated 2.0 to indicate it is identical to Swagger 2.0. You can recognize this because the first line of its YAML-format description will read:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"yaml\" class=\"language-yaml\">swagger: \"2.0\"<\/code><\/pre>\n\n\n\n<p>The entire OpenAPI 2.0 format is identical to Swagger 2.0, right down to the heading that identifies it as &#8220;swagger!&#8221;<\/p>\n\n\n\n<p>The most recent major version is OpenAPI 3.0, released in 2017. You can easily identify it based on the first line of its YAML:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"yaml\" class=\"language-yaml\">openapi: \"3.0.0\"<\/code><\/pre>\n\n\n\n<p>The OAI leaders who guide OpenAPI made a lot of improvements with the third version of the specification. Most notably, a \u201ccomponents\u201d section provides flexibility in describing many approaches to HTTP APIs. These components, which include request and response bodies, also add a way to describe webhooks with \u201ccallbacks.\u201d Additionally, the way of describing API hosts and base paths is simplified into a single object made of components.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">How to use Swagger and OpenAPI<a id=\"howtouseswaggerandopenapi\"><\/a><\/h2>\n\n\n\n<p>Many tools exist for Swagger, and it\u2019s still widely supported despite OpenAPI 3.0 superseding it as the latest format in 2017. The best tools will accept multiple formats, so you should be able to bring either a Swagger 2.0 an OpenAPI 3.0 document to modern tooling.<\/p>\n\n\n\n<p>The biggest advantage of an API description is that your documentation will always be up-to-date. You\u2019ll ensure that anyone using your API sees the absolute latest functionality. You can also use the Swagger or OpenAPI definition to test your APIs, to be certain that what is in your description (and what gets generated as documentation) matches your deployment. Finally, since API descriptions are machine readable, there are several other utilities you can generate using the definition, including servers and SDKs.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"keep-api-documentation-updated\">Keep API documentation updated<\/h2>\n\n\n\n<p><a href=\"https:\/\/readme.com\/documentation#swagger\">Once you have a Swagger or OpenAPI file<\/a>, you can use it to ensure your documentation is always accurate. The description format provides the structure that becomes your API reference. This part of your documentation can be generated every time the API changes and can be hosted alongside the rest of your documentation.<\/p>\n\n\n\n<p>Our <a href=\"https:\/\/readme.com\/resources\/best-practices-for-writing-updating-api-docs\/\">best practices for writing API docs<\/a> suggest some good ways to get started, including \u201cautodoc\u201d tools to generate your reference. These can be built into continuous integration pipelines, described later in this guide. Essentially, you can deploy updated docs along with your API.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"test-api-contracts\">Test API contracts<\/h2>\n\n\n\n<p>Another common use of Swagger and OpenAPI documents is to confirm your API behaves the way you say it does. API definitions are also sometimes called <em>contracts <\/em>because they describe exactly what the API provider agrees will be included. You can run sample calls against your API\u2014either in development or production\u2014and make sure each request returns the expected response.<\/p>\n\n\n\n<p>For example, your API description may declare the following fields in JSON:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"json\" class=\"language-json\">{\n  \"id\": 8675309,\n  \"name\": \"Jenny\",\n  \"status\": \"available\"\n}<\/code><\/pre>\n\n\n\n<p>But the API may actually provide a different response:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"json\" class=\"language-json\">{\n  \"pet_id\": 8675309,\n  \"name\": \"Jenny\",\n  \"status\": 1\n}<\/code><\/pre>\n\n\n\n<p>The errors might not be immediately obvious when examined by eye. Using an automated diff tool, you can quickly discover what\u2019s amiss.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/lh5.googleusercontent.com\/OZ6ICRlQwpkm6jPqG7B5dNHPLtAeXQZwWUre_6Jh0NASHFnuGYjmwBmcTOwXfSl2Ek0EkOmho3QXwLqNoEquKoZua7N-Gi4PHpwzcOA4KNPyAD_r9DCromwnmmTb3JoLCahvdxEB\" alt=\"Automated diffing using JSONDiff to identify differences between expectation and reality\"\/><figcaption class=\"wp-element-caption\"><span style=\"white-space: pre-wrap;\">Automated diffing using <\/span><a href=\"http:\/\/www.jsondiff.com\/\"><span style=\"white-space: pre-wrap;\">JSONDiff<\/span><\/a><span style=\"white-space: pre-wrap;\"> to identify differences between expectation and reality.<\/span><\/figcaption><\/figure>\n\n\n\n<p>In this case, the diffing tool shows that <code>id<\/code> became <code>pet_id<\/code>. The <code>status<\/code> field, which we expected to be a string, was implemented as an integer. When problems like these are discovered early, you can ensure the API is developed according to the contract\u2014or, make the appropriate edits in your API definition so that the documentation will match the implementation.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"generate-servers-sdks-and-sample-code\">Generate Servers, SDKs, and Sample Code<\/h2>\n\n\n\n<p>It turns out when something is machine readable, there are all sorts of automated activities that become possible. In addition to documentation and contract testing, you can:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Stub out code to help build your API<\/li>\n\n\n\n<li>Create mock servers for front-end testing<\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/readmeio\/api\">Generate wrapper libraries or SDKs<\/a> in multiple languages<\/li>\n\n\n\n<li>Build code samples automatically<\/li>\n<\/ul>\n\n\n\n<p>OpenAPI descriptions allow you to make your documentation far more than a simple API reference.<\/p>\n\n\n\n<p>The screenshot below shows a starter Python code snippet that ReadMe automatically generated from a single API description file. Also generated from the same description were equivalent snippets for JavaScript, Ruby, Node, and cURL (not shown).<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/readme-openapi-codesamples.png\" alt=\"Sample code snippets generated from an API description file\"\/><\/figure>\n\n\n\n<p>When you give developers the code in their own language with personalized sample code, they are a simple copy-and-paste away from their first \u201chello world\u201d success with your API!<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">How to write an OpenAPI description<a id=\"howtowriteanopenapidescription\"><\/a><\/h2>\n\n\n\n<p>You\u2019ve seen there\u2019s a lot you can do with a Swagger or OpenAPI file. Now you\u2019ll want to create your own! Since it\u2019s plain text format, you can use any text editor. However, it makes sense to use one that knows the syntax of the API description format you\u2019re using. In addition, it can be helpful to begin with a template so you don\u2019t have to start from scratch (we&#8217;ve got one for you!).<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"use-json-or-yaml\">Use JSON or YAML<\/h3>\n\n\n\n<p>When you write your OpenAPI or Swagger docs, you can choose from either of two formats: <a href=\"https:\/\/www.json.org\/json-en.html\">JSON<\/a> or <a href=\"https:\/\/yaml.org\/\">YAML<\/a>. Both will use the same data structure (determined by the Swagger or OpenAPI specification), but each will have a different syntax representation. JSON may look familiar to most web developers and it is the most common format used to return actual API results. YAML may also look familiar, as it\u2019s often used in configuration files.<\/p>\n\n\n\n<p><strong>YAML<\/strong> uses whitespace and minimal markup, which can make it more human-readable compared to JSON.<\/p>\n\n\n\n<p>Below is an example OpenAPI 3 YAML description, showing the header and one path\/response.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"yaml\" class=\"language-yaml\">openapi: \"3.0.0\"\ninfo:\n  version: 1.0.0\n  title: Swagger Petstore\n  license:\n    name: MIT\nservers:\n  - url: http:\/\/petstore.swagger.io\/v1\npaths:\n  \/pets:\n    get:\n      summary: List all pets\n      operationId: listPets\n      tags:\n        - pets\n      parameters:\n        - name: limit\n          in: query\n          description: How many items to return at one time (max 100)\n          required: false\n          schema:\n            type: integer\n            format: int32\n      responses:\n        '200':\n          description: A paged array of pets\n          headers:\n            x-next:\n              description: A link to the next page of responses\n              schema:\n                type: string\n          content:\n            application\/json:\n                  schema:\n                $ref: \"#\/components\/schemas\/Pets\"<\/code><\/pre>\n\n\n\n<p><strong>JSON <\/strong>is the more common format for data exchange, but is less human-readable. Here\u2019s the same OpenAPI 3 description fomatted using JSON:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"json\" class=\"language-json\">{\n   \"openapi\": \"3.0.0\",\n   \"info\": {\n      \"version\": \"1.0.0\",\n      \"title\": \"Swagger Petstore\",\n      \"license\": {\n         \"name\": \"MIT\"\n      }\n   },\n   \"servers\": [\n      {\n         \"url\": \"http:\/\/petstore.swagger.io\/v1\"\n      }\n   ],\n   \"paths\": {\n      \"\/pets\": {\n         \"get\": {\n            \"summary\": \"List all pets\",\n            \"operationId\": \"listPets\",\n            \"tags\": [\n               \"pets\"\n            ],\n            \"parameters\": [\n               {\n                  \"name\": \"limit\",\n                  \"in\": \"query\",\n                  \"description\": \"How many items to return at one time (max 100)\",\n                  \"required\": false,\n                  \"schema\": {\n                     \"type\": \"integer\",\n                     \"format\": \"int32\"\n                  }\n               }\n            ],\n            \"responses\": {\n               \"200\": {\n                  \"description\": \"A paged array of pets\",\n                  \"headers\": {\n                     \"x-next\": {\n                        \"description\": \"A link to the next page of responses\",\n                        \"schema\": {\n                           \"type\": \"string\"\n                        }\n                     }\n                  },\n                  \"content\": {\n                     \"application\/json\": {\n                        \"schema\": {\n                           \"$ref\": \"#\/components\/schemas\/Pets\"\n                        }\n                     }\n                  }\n               }\n            }\n         }\n      }\n   }\n}<\/code><\/pre>\n\n\n\n<p>Modern programming languages and their respective web frameworks can readily consume JSON objects, and this is a major reason for why many API providers adopt the JSON format. Most web developers are familiar with JSON syntax thanks to its resemblance to Javascript.<\/p>\n\n\n\n<p>Neither YAML or JSON are immune to human error, but editors with linters will catch the most common errors.<\/p>\n\n\n\n<blockquote class=\"wp-block-quote is-layout-flow wp-block-quote-is-layout-flow\">\n<p><strong>You can convert files between JSON and YAML, so feel free to choose whichever format is preferable for you and your team.<\/strong><\/p>\n<\/blockquote>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"your-favorite-code-editor\">Your favorite code editor<\/h3>\n\n\n\n<p>Your current development environment or text editor will include YAML and JSON syntax highlighting and may already include Swagger and OpenAPI syntax support as well. Look for plugins, which can help with syntax suggestions or checking for errors as you write your API description. Alternatively, you can use existing open source or web-based tools.<\/p>\n\n\n\n<p>For example, the VSCode editor has an <a href=\"https:\/\/marketplace.visualstudio.com\/items?itemName=mermade.openapi-lint\">open source linter plugin<\/a> to check YAML and JSON files against Swagger and OpenAPI specifications.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/linter_showing_missing_property_swagger.png\" alt=\"Code editor with Swagger linter\"\/><\/figure>\n\n\n\n<p><\/p>\n\n\n\n<p>Shown above is an example of an in-editor linter program which will raise errors and flag conventions for cleaner code. You can click each error to go to the line where the issue originated. In the screenshot, we accidentally misspelled <code>description<\/code>, resulting in the linter raising missing required property errors on line 48 with the typo.<\/p>\n\n\n\n<p>With most editors, you can edit either OpenAPI or Swagger files in YAML, with syntax help and built-in linting. When finished, you can programmatically convert YAML to the equivalent JSON.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">OpenAPI template<a id=\"openapitemplate\"><\/a><\/h2>\n\n\n\n<p>To get started with an OpenAPI file, it can be helpful to start with a basic outline that includes the essential syntax. Then you can step through each line and make edits to include the proper details from your API.<\/p>\n\n\n\n<p><strong>You don\u2019t have to start from scratch! Here&#8217;s a template OpenAPI definition:<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"JavaScript\" class=\"language-JavaScript\">openapi: \"3.0.0\"\ninfo:\n  version: 1.0.0 \/\/ Version of your API\n  title: Your API Title\n  description: An API description template\n  contact:\n    name: Your Name\n    email: email@example.com\n    url: http:\/\/example.com\n  license:\n    name: License Name\n    url: http:\/\/example.com\/license-url\nservers:\n  - url: http:\/\/api.example.com\npaths:\n  \/your_endpoint:\n    get:\n      description: |\n        Multi-line description\n        of your API endpoint\n      operationId: yourOperation\n      parameters:\n        - name: your_param\n          in: query\n          description: Description of your param\n          required: false\n          schema:\n            type: string\n      responses:\n        '200':\n          description: Your success description<\/code><\/pre>\n\n\n\n<p>This template doesn\u2019t include complete coverage of all possible OpenAPI fields, but it\u2019s useful as starter code. In most cases you\u2019ll want to add your own response schemas and reusable components. You can dig into the <a href=\"https:\/\/github.com\/OAI\/OpenAPI-Specification\">OAS specification<\/a> itself or see our OpenAPI and Swagger examples below.<\/p>\n\n\n\n<p>Once you have an initial framework for your API described, you can complete coverage for the remainder of your API.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"generate-openapi-from-an-existing-api\">Generate OpenAPI from an existing API<\/h3>\n\n\n\n<p>If you already have an API in production, you can benefit from documenting it in an OpenAPI file. To save yourself some time, look for some ways you can generate the descriptions from your code or live traffic.<\/p>\n\n\n\n<p>If your API is built in a common framework, such as Falcon (Python) or Rails (Ruby), your code already has everything needed to create a Swagger or OpenAPI description. Look for an existing project that creates an API definition based on an existing API. For example, <a href=\"https:\/\/github.com\/zhandao\/zero-rails_openapi\"><code>zero-rails_openapi gem<\/code><\/a> is a Rails solution and <a href=\"https:\/\/pypi.org\/project\/falcon-apispec\/\"><code>falcon-apispec<\/code><\/a> does the same for Falcon.\n\n\n\n<p>There could be many reasons it&#8217;s not possible to reference source code. In that case, you might use a service like <a href=\"https:\/\/www.useoptic.com\/\">Optic<\/a> to listen to live API traffic. After reviewing live requests and responses, Optic can output an OpenAPI or Swagger file.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Swagger and OpenAPI best practices<a id=\"swaggerandopenapibestpractices\"><\/a><\/h2>\n\n\n\n<p>When describing HTTP APIs, you want to keep an overall developer experience in mind. If your documentation is going to be comprehensive, your Swagger or OpenAPI definition must also have full API coverage. If the API is still in development, it\u2019s also a good time to ensure you\u2019re following API design best practices in naming fields and using HTTP methods.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"adopt-rest-patterns\">Adopt REST patterns<\/h3>\n\n\n\n<p>Even before you write descriptions for your endpoints, you\u2019ll need to decide which are needed and how they\u2019re named. With thousands of HTTP APIs available to developers, there\u2019s no reason to get super creative with how yours is designed. Look to established conventions rather than adopting an unnecessarily unique take. Developers are comfortable with these patterns, as they\u2019ve experienced them across many APIs. The more similar you can be to something they\u2019ve seen before, the easier time they\u2019ll have integrating with your API.<\/p>\n\n\n\n<p>Representational State Transfer (REST) is an architectural style often used by HTTP APIs. While most don\u2019t adopt the patterns wholesale, there are three big criteria to keep in mind for your API:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>Organize your API around resources<\/li>\n\n\n\n<li>Use HTTP methods to communicate actions<\/li>\n\n\n\n<li>Rely upon standard HTTP status codes<\/li>\n<\/ol>\n\n\n\n<p>The RESTful approach to APIs came out of a time that heavily relied upon remote procedure calls (RPC). In these approaches, led by SOAP APIs, you might make a call to a <code>getPets<\/code> procedure, similar to how a local function is called in code.<\/p>\n\n\n\n<p>Instead, REST uses a <code>pets<\/code> resource. To retrieve the list of pets, you would use the HTTP GET verb on the <code>\/pets<\/code> endpoint. The success or failure of that call would be returned as the HTTP status code 200 if it worked and most often a 400-level error if it didn\u2019t.<\/p>\n\n\n\n<p>One positive side effect, which comes through in your Swagger or OpenAPI definition, is that the actions for each resource are naturally grouped together. They\u2019ll also likely call upon the same components, such as the Pet schema in this example. The REST convention and API description formats encourage straightforward designs that improve developer experiences. However, it still takes some effort on your part to keep the interface uniform.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/Sleeping.psd.png\" alt=\"Owlbert, sleeping in a bed\"\/><figcaption class=\"wp-element-caption\"><span style=\"white-space: pre-wrap;\">Owlbert, adopting REST patterns.<\/span><\/figcaption><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"start-with-friendly-descriptions\">Start with friendly descriptions<\/h3>\n\n\n\n<p>Your API definition includes technical details of the API, but there are also human-readable areas throughout the document. These <code>description<\/code> and <code>summary<\/code> fields are used throughout the definition. An endpoint requires a summary of how each HTTP method is used. Parameters and responses within those also need descriptions. The words used here are important\u2014they\u2019ll be output with documentation and read by every developer who uses the API.<\/p>\n\n\n\n<p>When these fields are blank or\u2014perhaps worse\u2014use unhelpful placeholder text, your documentation will suffer. Put yourself in the place of someone using the API. You\u2019d want to know the purpose of each endpoint and context around the expected inputs and outputs.<\/p>\n\n\n\n<p>For an example of bad documentation, this OpenAPI snippet will create documentation without a summary or description for the user:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"JavaScript\" class=\"language-JavaScript\">paths:\n  \/pets:\n    get:\n      summary:\n       operationId: getPets\n      tags:\n        - pets\n      parameters:\n        - name: limit\n          in: query\n          description:\n          required: false\n          schema:\n            type: integer\n            format: int32<\/code><\/pre>\n\n\n\n<p>Better documentation includes a summary and description with useful info on how one would use the endpoint.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"JavaScript\" class=\"language-JavaScript\">paths:\n  \/pets:\n    get:\n      summary: Retrieve a list of pets, up to the passed limit (if included, otherwise 10)\n      operationId: getPets\n      tags:\n        - pets\n      parameters:\n        - name: limit\n          in: query\n          description: The number of pets to retrieve (maximum 100)\n          required: false\n          schema:\n            type: integer\n            format: int32<\/code><\/pre>\n\n\n\n<p>API descriptions are most useful for being machine readable, but you can\u2019t completely forget the human who will be consuming the API.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"be-consistent-with-naming\">Be consistent with naming<\/h3>\n\n\n\n<p>The endpoints for your API could work just fine with meaningless names. Similarly, the fields in your parameters and results don\u2019t technically need human-readable labels. But you don\u2019t typically see API calls like <code>\/c109b523f7?755ef5=100<\/code>. People can\u2019t hold the purpose of this call in their heads long enough to copy it from docs to code.<\/p>\n\n\n\n<p><strong>Naming within your API matters<\/strong><\/p>\n\n\n\n<p>In a RESTful approach to API design, you\u2019re organizing your API around resources. A common naming tactic is to use nouns for resources. Should these nouns be singular or plural? There\u2019s a hot debate, but most practitioners can agree on one thing: you should make a choice and stick with it the same way for your API (and all your APIs, if possible). That means, if you are adding orders to your API, you\u2019d choose <code>\/orders<\/code> over <code>\/order<\/code> to match the existing <code>\/pets<\/code> endpoint.<\/p>\n\n\n\n<p>You also want to strive for consistency in naming fields. If you use a <code>limit<\/code> parameter on one endpoint, you wouldn\u2019t use <code>max_returned<\/code> for another endpoint. Also consider capitalization and punctuation in field names. You wouldn\u2019t want <code>petName<\/code> and <code>Pet_ID<\/code> fields in the same API. Choose a naming convention and stick with it.<\/p>\n\n\n\n<p>These \u201crules\u201d aren\u2019t about appeasing perfection. They\u2019re there to help developers have a seamless experience with your API. When names are predictable, sometimes developers won\u2019t even need to reference your documentation to make a tweak to their code.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"continuous-integration-and-delivery\">Continuous integration and delivery<\/h3>\n\n\n\n<p>Finally, let\u2019s talk about what happens <em>after <\/em>your Swagger and OpenAPI definitions are created. You need some way to generate documentation. Ideally, this process would happen automatically. Otherwise, you could go to all this work to describe your API and still end up with outdated documentation!<\/p>\n\n\n\n<p>Many software teams use a continuous integration (CI) pipeline as part of their development workflow. Here, when changes to code are introduced, tests automatically run against the changed code to check for issues. Similarly, when those changes are accepted, teams can automatically deploy the code to a staging environment for further testing, or directly to production if the team has adopted continuous delivery (CD) practices.<\/p>\n\n\n\n<p>Your Swagger or OpenAPI files can use similar processes to keep documentation and other API resources updated. In fact, if your API description is stored alongside your API code, your documentation can be deployed alongside the API it supports.<\/p>\n\n\n\n<p>There are various CI\/CD tools, so the exact implementation depends upon your toolset and workflow. ReadMe handles this internally by first generating an OpenAPI file from code with every deploy. We use our <a href=\"https:\/\/github.com\/readmeio\/swagger-inline\">swagger-inline<\/a> library to create the API description, then upload it to our hosted documentation with the <a href=\"https:\/\/www.npmjs.com\/package\/rdme\">rdme<\/a> Node package.<\/p>\n\n\n\n<p>No matter your workflow, the result should be the same: auto-generated documentation every time the API changes.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Swagger and OpenAPI tools<a id=\"swaggerandopenapitools\"><\/a><\/h2>\n\n\n\n<p>We\u2019ve already mentioned several ways to use Swagger and OpenAPI files. Because they are machine-readable formats, there are endless ways you could use them. Developers have already created many open source projects based around API descriptions. Pick your use case and check out some tools to give your Swagger and OpenAPI projects a boost.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"generate-documentation\">Generate documentation<\/h3>\n\n\n\n<p>The easiest way to see how your OpenAPI or Swagger file looks as documentation is to <a href=\"https:\/\/preview.readme.io\/reference\/?url=\">generate it with ReadMe<\/a>. You can add a URL to the query string to see it live. Or use our <a href=\"https:\/\/readme.com\/documentation#swagger\">Swagger upload form<\/a> and simply paste in your Swagger or OpenAPI URL (such as a raw GitHub reference).<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/lh6.googleusercontent.com\/kdLCdsS3I8rPy1KQTgZIbERKElSF9IHek_LnNSWmXGFV8a_U94suHuJr13dK6eztlcuUSrWFKISjtPB8TopGvE1MB80Zq2m6RhhaTMZ6SH8TepuiCj0QC3fbJw0ennIjOeEDm1kc\" alt=\"Stylized rendering of three-pane API documentation view\"\/><\/figure>\n\n\n\n<p>To generate a basic reference locally for your OpenAPI project, you might start with an open source tool. There are a handful listed on <a href=\"https:\/\/openapi.tools\/#documentation\">OpenAPI.tools<\/a>.<\/p>\n\n\n\n<p>You can render a preview of your API Reference in ReadMe using the form below!<\/p>\n\n\n\n<form class=\"swagger-demo\" action=\"https:\/\/preview.readme.io\/reference\" method=\"GET\" target=\"\u201c_blank\u201d\">\n<div class=\"flex\"><label for=\"swagger-demo\">OpenAPI\/Swagger Description (URL)<\/label> <input id=\"swagger-demo1\" title=\"URL starting with https:\/\/\" name=\"url\" pattern=\"https:\/\/.*\" type=\"url\" placeholder=\"https:\/\/yourdomain.com\/swagger.json\"> <button>Render API Docs!<\/button><\/div>\n<\/form>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"stub-out-your-code\"><strong>Stub out your code<\/strong><\/h3>\n\n\n\n<p>Whether it is a temporary end to your API while you design the next phase, or a permanent end to each of your API points, here are a few links to help you tie up all your loose ends. The documentation for each package will be very helpful to get you started or keep you going:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The Node.js package <a href=\"https:\/\/github.com\/isa-group\/oas-tools\"><strong>oas-tools<\/strong><\/a>, is the OpenAPI 3.0 go-to, as it is an update to <a href=\"https:\/\/github.com\/apigee-127\/swagger-tools\">swagger-tools<\/a> and <a href=\"https:\/\/github.com\/anttiviljami\/openapi-backend\">openapi-backend<\/a>. All three have their uses though, as the last two may be especially useful if you are working on or updating an existing project written in Swagger 1.0, or 2.0.<\/li>\n\n\n\n<li>If you are writing in Python, <a href=\"https:\/\/github.com\/NotJustAToy\/falcon-heavy\">falcon-heavy<\/a> will be your go-to.<\/li>\n\n\n\n<li>PHP users can find what they need from <a href=\"https:\/\/github.com\/api-platform\/api-platform\">api-platform<\/a> or by checking out <a href=\"https:\/\/github.com\/apioo\/fusio\">fusio<\/a>.<\/li>\n<\/ul>\n\n\n\n<p>You can find more server implementations at <a href=\"https:\/\/openapi.tools\/#server\">https:\/\/openapi.tools\/#server<\/a>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"test-your-apis\">Test your APIs<\/h3>\n\n\n\n<p>When you or your team feel your design is ready for an API testing session, check out these packages:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/byu-oit\/openapi-enforcer\">OpenAPI Enforcer<\/a> is another popular choice that works with both OpenAPI 2.0 and 3.0.<\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/interagent\/committee\">Committee for Ruby<\/a> is a validator for JSON Schema, OpenAPI 2.0, and OpenAPI 3.0 specific to recent Ruby (versions 2.4+).<\/li>\n<\/ul>\n\n\n\n<p>These tools should help you understand and troubleshoot your project as it cycles through its various starts and finishes.<\/p>\n\n\n\n<h1 class=\"wp-block-heading\">Swagger and OpenAPI examples<a id=\"swaggerandopenapiexamples\"><\/a><\/h1>\n\n\n\n<p>Many companies maintain Swagger or OpenAPI files to describe their APIs and build documentation. At ReadMe, 85% of customers have an API reference, typically generated directly from an API description file like the ones reviewed above. We\u2019ve gathered some examples of public API definitions so you can learn from what\u2019s already been published.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"swagger-petstore\">Swagger Petstore<\/h3>\n\n\n\n<p>A classic example is the Swagger Petstore API definition. You can find it in multiple formats and specification versions:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/2.0\/yaml\/petstore.yaml\">Swagger \/ OpenAPI 2.0 YAML<\/a> and <a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/2.0\/json\/petstore.json\">JSON<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/yaml\/petstore.yaml\">OpenAPI 3.0 YAML<\/a> and <a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/json\/petstore.json\">JSON<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/yaml\/petstore-expanded.yaml\">Expanded example YAML<\/a> and <a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/json\/petstore-expanded.json\">JSON<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/yaml\/callback-example.yaml\">Callback example YAML<\/a> and <a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/json\/callback-example.json\">JSON<\/a><\/li>\n<\/ul>\n\n\n\n<p>While useful to see these hypothetical examples, you might prefer to see how live APIs have used OpenAPI and Swagger.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"api-descriptions-in-production\">API descriptions in production<\/h3>\n\n\n\n<p>Most Swagger and OpenAPI files live in private code repositories and behind firewalls. However, there are many examples of public APIs that also publish an API definition. Here are a few to review:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/yaml\/readme.yaml\">ReadMe YAML<\/a> and <a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/json\/readme.json\">JSON<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/sendgrid\/sendgrid-oai\/blob\/master\/oai.yaml\">SendGrid YAML<\/a> and <a href=\"https:\/\/github.com\/sendgrid\/sendgrid-oai\/blob\/master\/oai.json\">JSON<\/a><\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/OAI\/OpenAPI-Specification\/blob\/master\/examples\/v2.0\/yaml\/uber.yaml\">Uber YAML<\/a> and <a href=\"https:\/\/github.com\/OAI\/OpenAPI-Specification\/blob\/master\/examples\/v2.0\/json\/uber.json\">JSON<\/a> (Swagger \/ OpenAPI 2.0 format)<\/li>\n\n\n\n<li><a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/yaml\/uspto.yaml\">US Patent and Trademark YAML<\/a> and <a href=\"https:\/\/github.com\/readmeio\/oas\/blob\/master\/packages\/examples\/3.0\/json\/uspto.json\">JSON<\/a><\/li>\n<\/ul>\n\n\n\n<p>That\u2019s just a sampling of what\u2019s available. ReadMe maintains a <a href=\"https:\/\/github.com\/readmeio\/oas\/tree\/master\/packages\/examples\">curated list of example API descriptions<\/a>.<\/p>\n\n\n\n<p>Still need more examples? Try out this <a href=\"https:\/\/www.google.com\/?q=openapi%20filetype:yaml\">Google search to query the web for &#8220;OpenAPI&#8221; files with with filetype:YAML<\/a>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">OpenAPI and future versions of OAS<a id=\"OpenAPIandFutureVersionsofOAS\"><\/a><\/h2>\n\n\n\n<p>It\u2019s clear that API descriptions are here to stay. Thousands of companies depend upon these machine-readable definitions. OpenAPI is the next version of Swagger, but they co-exist. We may see other formats rise in popularity and there will certainly be new versions of OpenAPI.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"openapi-versions\">OpenAPI versions<\/h3>\n\n\n\n<p>In addition to OpenAPI 2.0 (the backward-compatible Swagger 2.0 format) and OpenAPI 3.0, there are other versions to consider now and into the future.<\/p>\n\n\n\n<p>The current version of OpenAPI (as of June 2020) is version 3.0.3. This version was released in February 2020, following version 3.0.2 (October 2018), 3.0.1 (December 2017), and 3.0.0 (July 2017).<\/p>\n\n\n\n<p>The OpenAPI <a href=\"https:\/\/www.openapis.org\/blog\/2020\/06\/18\/openapi-3-1-0-rc0-its-here\">3.1.0 release candidate was announced on June 18, 2020<\/a>. While considered a minor version based on <a href=\"https:\/\/semver.org\/\">semantic versioning<\/a> (previous releases were considered patches), the next version has a number of <a href=\"https:\/\/github.com\/OAI\/OpenAPI-Specification\/issues\/1466\">candidate features<\/a> that warrant the version update. The most significant changes are:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>A new top-level element for describing webhooks that are registered, and managed out of band.<\/li>\n\n\n\n<li>Support for identifying API licenses using the standard SPDX identifier.<\/li>\n\n\n\n<li>The PathItems object is now optional to make it simpler to create reusable libraries of components. Reusable PathItems can be described in the components object. There is also support for describing APIs secured using client certificates.<\/li>\n<\/ol>\n\n\n\n<p>There is <a href=\"https:\/\/github.com\/OAI\/OpenAPI-Specification\/issues\/2219\">discussion within the community<\/a> about whether the changes within OpenAPI are so large that a major version change to OpenAPI 4.0 would be more appropriate.<\/p>\n\n\n\n<p>With OpenAPI likely to fully adopt JSON Schema with its next release, some features are not fully backward compatible. Regardless of the version number, there will be some effort required to ensure that OpenAPI documents are supported throughout the ecosystem.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" id=\"alternatives-to-openapi\">Alternatives to OpenAPI<\/h3>\n\n\n\n<p>Before OpenAPI existed, there were already some API description formats. Often these formats were championed by organizations with supported tooling.<\/p>\n\n\n\n<p>Some well-known alternative HTTP API description formats include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Swagger, which later became OpenAPI<\/li>\n\n\n\n<li><a href=\"https:\/\/raml.org\/\">RAML<\/a>, based on YAML, which calls itself a \u201cmodeling language\u201d<\/li>\n\n\n\n<li><a href=\"https:\/\/apiblueprint.org\/\">API Blueprint<\/a>, a Markdown-like syntax, now part of Oracle<\/li>\n<\/ul>\n\n\n\n<p>Other related formats include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"http:\/\/spec.graphql.org\/\">GraphQL<\/a>, a data query language with an alternative API.<\/li>\n\n\n\n<li><a href=\"https:\/\/json-schema.org\/\">JSON Schema<\/a>, a vocabulary for describing JSON data (used in OpenAPI)<\/li>\n\n\n\n<li><a href=\"https:\/\/www.asyncapi.com\/\">AsyncAPI<\/a>, a format for event-driven architectures<\/li>\n<\/ul>\n\n\n\n<p>Swagger solved the problem of documentation out of sync with deployed code, and became the de facto API description format when developers recognized its utility. Machine-readable API definitions opened up a lot of doors to automation for API providers and consumers. The industry has rallied around the OpenAPI format as its successor to Swagger, but any format could overtake it by solving developer problems better.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2020\/07\/xkcd_standards.png\" alt=\"xkcd comic\"\/><figcaption class=\"wp-element-caption\"><a href=\"https:\/\/xkcd.com\/927\/\"><span style=\"white-space: pre-wrap;\">xkcd #927<\/span><\/a><\/figcaption><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"generate-beautiful-documentation\">Generate (beautiful) documentation<\/h2>\n\n\n\n<p>For the foreseeable future, OpenAPI remains the standard API description format for defining your API. There are many ways it can be used to improve your APIs, most notably to automatically generate documentation.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/lh5.googleusercontent.com\/IiwPAON4LtqlLSzi5USTwLBk6j5TT7Xi0OH-9g0RshMB2IG24jE-T_5q6w7_PrEvwZvMZ6iEnJpbBqvSn9Zrj8hq6N20l54RqJRIpvhCMSEV1SCiAuXsmtnoCSiKTPqqkuwyzHNP\" alt=\"Stylized rendering of three-pane API documentation view\"\/><\/figure>\n\n\n\n<p>The simplicity of the OpenAPI format helps you focus on the details that matter most within your API. When those descriptions translate into beautiful documentation like <a href=\"https:\/\/readme.com\/documentation\">API references generated by ReadMe<\/a>, you\u2019ll give developers a much better integration experience. Even better, the documentation will always be in sync with your API, removing one of the biggest developer headaches.<\/p>\n\n\n\n<p>Once you\u2019ve got your hands on an OpenAPI file, <a href=\"https:\/\/readme.com\/documentation#swagger\">try uploading it to ReadMe<\/a>! We\u2019ll host a beautiful reference guide for your API, for free.<\/p>\n\n\n\n<form class=\"swagger-demo\" action=\"https:\/\/preview.readme.io\/reference\" method=\"GET\" target=\"\u201c_blank\u201d\">\n<div class=\"flex\"><label for=\"swagger-demo\">OpenAPI\/Swagger Description (URL)<\/label> <input id=\"swagger-demo\" title=\"URL starting with https:\/\/\" name=\"url\" pattern=\"https:\/\/.*\" type=\"url\" placeholder=\"https:\/\/yourdomain.com\/swagger.json\"> <button>Render API Docs!<\/button><\/div>\n<\/form>\n","protected":false},"excerpt":{"rendered":"<p>Excellent API documentation experiences stem from proper use of an OpenAPI or Swagger API description file. In this guide, we explain Swagger and OpenAPI, how to create an OpenAPI or Swagger description for an API, and how to use the OpenAPI Specification to yield documentation that\u2019s continuously up-to-date and automated! HTTP API descriptions, like those [&hellip;]<\/p>\n","protected":false},"author":4,"featured_media":2908,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"content-type":"","inline_featured_image":false,"footnotes":""},"categories":[23,34],"tags":[45,13,44],"ppma_author":[53],"class_list":["post-2729","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-developer-experience","category-how-to","tag-developer-experience","tag-openapi","tag-swagger"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v23.0 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>How to Use OpenAPI and Swagger for Documentation - ReadMe: Resource Library<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"How to Use OpenAPI and Swagger for Documentation - ReadMe: Resource Library\" \/>\n<meta property=\"og:description\" content=\"Excellent API documentation experiences stem from proper use of an OpenAPI or Swagger API description file. In this guide, we explain Swagger and OpenAPI, how to create an OpenAPI or Swagger description for an API, and how to use the OpenAPI Specification to yield documentation that\u2019s continuously up-to-date and automated! HTTP API descriptions, like those [&hellip;]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation\" \/>\n<meta property=\"og:site_name\" content=\"ReadMe: Resource Library\" \/>\n<meta property=\"article:published_time\" content=\"2020-07-07T13:00:00+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2025-12-17T01:40:38+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png\" \/>\n\t<meta property=\"og:image:width\" content=\"200\" \/>\n\t<meta property=\"og:image:height\" content=\"200\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"Dom Harrington\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Miche Nickolaisen\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"24 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation\",\"url\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation\",\"name\":\"How to Use OpenAPI and Swagger for Documentation - ReadMe: Resource Library\",\"isPartOf\":{\"@id\":\"https:\/\/readme.com\/resources\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#primaryimage\"},\"image\":{\"@id\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#primaryimage\"},\"thumbnailUrl\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png\",\"datePublished\":\"2020-07-07T13:00:00+00:00\",\"dateModified\":\"2025-12-17T01:40:38+00:00\",\"author\":{\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/770bcc036178743133b5ba515195981b\"},\"breadcrumb\":{\"@id\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#primaryimage\",\"url\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png\",\"contentUrl\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png\",\"width\":200,\"height\":200},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/readme.com\/resources\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"How to Use OpenAPI and Swagger for Documentation\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/readme.com\/resources\/#website\",\"url\":\"https:\/\/readme.com\/resources\/\",\"name\":\"ReadMe: Resource Library\",\"description\":\"Making API documentation better for everyone\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/readme.com\/resources\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/770bcc036178743133b5ba515195981b\",\"name\":\"Miche Nickolaisen\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/image\/a24e32f88df84934c107cef6fa8d3223\",\"url\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/IMG_7151-scaled-e1718387764646.jpg\",\"contentUrl\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/IMG_7151-scaled-e1718387764646.jpg\",\"caption\":\"Miche Nickolaisen\"},\"description\":\"An Austin resident since 2009, Miche grew up in rural southwestern Missouri. When not working on ReadMe's content marketing, you can find them doing a number of hobbies, including (but not limited to) bouldering, martial arts, playing tabletop RPGs and\/or video games, bullet journaling, and making art. They live with a large menagerie of indoor pets and a smaller (outdoor) menagerie of feral cats they take care of (sometimes including a few possums and raccoons, just for good measure).\",\"url\":\"https:\/\/readme.com\/resources\/author\/miche\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"How to Use OpenAPI and Swagger for Documentation - ReadMe: Resource Library","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:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation","og_locale":"en_US","og_type":"article","og_title":"How to Use OpenAPI and Swagger for Documentation - ReadMe: Resource Library","og_description":"Excellent API documentation experiences stem from proper use of an OpenAPI or Swagger API description file. In this guide, we explain Swagger and OpenAPI, how to create an OpenAPI or Swagger description for an API, and how to use the OpenAPI Specification to yield documentation that\u2019s continuously up-to-date and automated! HTTP API descriptions, like those [&hellip;]","og_url":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation","og_site_name":"ReadMe: Resource Library","article_published_time":"2020-07-07T13:00:00+00:00","article_modified_time":"2025-12-17T01:40:38+00:00","og_image":[{"width":200,"height":200,"url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png","type":"image\/png"}],"author":"Dom Harrington","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Miche Nickolaisen","Est. reading time":"24 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation","url":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation","name":"How to Use OpenAPI and Swagger for Documentation - ReadMe: Resource Library","isPartOf":{"@id":"https:\/\/readme.com\/resources\/#website"},"primaryImageOfPage":{"@id":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#primaryimage"},"image":{"@id":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#primaryimage"},"thumbnailUrl":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png","datePublished":"2020-07-07T13:00:00+00:00","dateModified":"2025-12-17T01:40:38+00:00","author":{"@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/770bcc036178743133b5ba515195981b"},"breadcrumb":{"@id":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#primaryimage","url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png","contentUrl":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2020\/07\/How-to-Use-OpenAPI-Description-for-an-API.png","width":200,"height":200},{"@type":"BreadcrumbList","@id":"https:\/\/readme.com\/resources\/how-to-use-openapi-and-swagger-spec-for-documentation#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/readme.com\/resources\/"},{"@type":"ListItem","position":2,"name":"How to Use OpenAPI and Swagger for Documentation"}]},{"@type":"WebSite","@id":"https:\/\/readme.com\/resources\/#website","url":"https:\/\/readme.com\/resources\/","name":"ReadMe: Resource Library","description":"Making API documentation better for everyone","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/readme.com\/resources\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/770bcc036178743133b5ba515195981b","name":"Miche Nickolaisen","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/image\/a24e32f88df84934c107cef6fa8d3223","url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/IMG_7151-scaled-e1718387764646.jpg","contentUrl":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/IMG_7151-scaled-e1718387764646.jpg","caption":"Miche Nickolaisen"},"description":"An Austin resident since 2009, Miche grew up in rural southwestern Missouri. When not working on ReadMe's content marketing, you can find them doing a number of hobbies, including (but not limited to) bouldering, martial arts, playing tabletop RPGs and\/or video games, bullet journaling, and making art. They live with a large menagerie of indoor pets and a smaller (outdoor) menagerie of feral cats they take care of (sometimes including a few possums and raccoons, just for good measure).","url":"https:\/\/readme.com\/resources\/author\/miche"}]}},"authors":[{"term_id":53,"user_id":0,"is_guest":1,"slug":"dom-harrington","display_name":"Dom Harrington","avatar_url":{"url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/1516897618298.jpeg","url2x":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/1516897618298.jpeg"},"first_name":"Dom","last_name":"Harrington","position":"Open Source Engineer","slogan":"","description":"Dom joins the ReadMe team remotely from the UK. He enjoys cooking, long walks in the countryside and playing video games. You\u2019ll likely find him in ReadMe's open source repos frantically writing tests."}],"_links":{"self":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/2729","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/comments?post=2729"}],"version-history":[{"count":0,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/2729\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/media\/2908"}],"wp:attachment":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/media?parent=2729"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/categories?post=2729"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/tags?post=2729"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/ppma_author?post=2729"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}