diff --git a/README.md b/README.md index 00f7fff..2fc4c44 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ OpenAPI Initiative -Are you new to the OpenAPI specification? +Are you new to the OpenAPI Specification? Read our [Getting started](https://learn.openapis.org/) page first. diff --git a/best-practices.md b/best-practices.md index a69e751..50c6b75 100644 --- a/best-practices.md +++ b/best-practices.md @@ -6,19 +6,19 @@ nav_order: 4 # Best Practices -This page contains general pieces of advice which do not strictly belong to the [Specification Explained](specification) chapter because they are not directly tied to the OpenAPI Specification. +This page contains general pieces of advice which do not strictly belong to the [Specification Explained](specification) chapter because they are not directly tied to the OpenAPI Specification (OAS). -However, they greatly simplify creating and maintaining OpenAPI documents, so they are worth keeping in mind. +However, they greatly simplify creating and maintaining OpenAPI Descriptions (OADs), so they are worth keeping in mind. ## Use a Design-First Approach -Traditionally, two main approaches exist when creating OpenAPI documents: **Code-first** and **Design-first**. +Traditionally, two main approaches exist when creating OADs: **Code-first** and **Design-first**. - In the Code-first approach, **the API is first implemented in code**, and then its description is created from it, using code comments, code annotations or simply written from scratch. This approach does not require developers to learn another language so it is usually regarded as the easiest one. - Conversely, in Design-first, **the API description is written first** and then the code follows. The first obvious advantages are that the code already has a skeleton upon which to build, and that some tools can provide boilerplate code automatically. -There have been a number of heated debates over the relative merits of these two approaches but, in the opinion of the OpenAPI Initiative, the importance of using **Design-first** cannot be stressed strongly enough. +There have been a number of heated debates over the relative merits of these two approaches but, in the opinion of the OpenAPI Initiative (OAI), the importance of using **Design-first** cannot be stressed strongly enough. The reason is simple: **The number of APIs that can be created in code is far superior to what can be described in OpenAPI**. To emphasize: **OpenAPI is not capable of describing every possible HTTP API, it has limitations**. @@ -26,7 +26,7 @@ Therefore, unless these descriptive limitations are perfectly known and taken in Sometimes, however, since it is late in the process, it will be preferred to twist the API description so that it matches *more or less* the actual API. It goes without saying that this leads to **unintuitive and incomplete descriptions**, that will rarely scale in the future. -Finally, there exist a number of [validation tools](https://tools.openapis.org/categories/data-validators) that can verify that the implemented code adheres to the OpenAPI description. Running these tools as part of a Continuous Integration process allows changing the OpenAPI document with peace of mind, since deviations in the code behavior will be promptly detected. +Finally, there exist a number of [validation tools](https://tools.openapis.org/categories/data-validators) that can verify that the implemented code adheres to the OpenAPI description. Running these tools as part of a Continuous Integration process allows changing the OpenAPI Description with peace of mind, since deviations in the code behavior will be promptly detected. > **Bottom line:** > OpenAPI opens the door to a [wealth of automated tools](https://tools.openapis.org). Make sure you use them! @@ -41,21 +41,21 @@ For instance, it is also commonplace to use code annotations to generate an Open Alternatively, you can use a Continuous Integration test to ensure that the two sources stay consistent. -## Add OpenAPI Documents to Source Control +## Add OpenAPI Descriptions to Source Control -OpenAPI descriptions are **not** just a documentation artifact: they are **first-class source files** which can drive a great number of automated processes, including boilerplate generation, unit testing and documentation rendering. +OpenAPI Descriptions are **not** just a documentation artifact: they are **first-class source files** which can drive a great number of automated processes, including boilerplate generation, unit testing and documentation rendering. -As such, OpenAPI description should be committed to source control, and, in fact, they should be among the first files to be committed. From there, they should also participate in Continuous Integration processes. +As such, OADs should be committed to source control, and, in fact, they should be among the first files to be committed. From there, they should also participate in Continuous Integration processes. -## Make the OpenAPI Documents Available to the Users +## Make the OpenAPI Descriptions Available to the Users -Beautifully-rendered documents can be very useful for the users of an API, but sometimes they might want to access the source OpenAPI description. For instance, to use tools to generate client code for them, or to build automated bindings for some language. +Beautifully-rendered documentation can be very useful for the users of an API, but sometimes they might want to access the source OAD. For instance, to use tools to generate client code for them, or to build automated bindings for some language. -Therefore, making the OpenAPI documents available to the users is an added bonus for them. The document can even be made available through the same API to allow runtime discovery. +Therefore, making the OAD available to the users is an added bonus for them. The documents that make up the OAD can even be made available through the same API to allow runtime discovery. -## There is Seldom Need to Write OpenAPI Documents by Hand +## There is Seldom Need to Write OpenAPI Descriptions by Hand -Since OpenAPI documents are plain text files, in an easy-to-read format (be it JSON or YAML), API designers are usually tempted to write them by hand. +Since OADs are plain text documents, in an easy-to-read format (be it JSON or YAML), API designers are usually tempted to write them by hand. While there is nothing stopping you from doing this, and, in fact, hand-written API descriptions are usually the most terse and efficient, approaching any big project by such method is highly impractical. @@ -63,23 +63,23 @@ Instead, you should try the other existing creation methods and choose the one t - **OpenAPI Editors**: Be it [text editors](https://tools.openapis.org/categories/text-editors) or [GUI editors](https://tools.openapis.org/categories/gui-editors) they usually take care of repetitive tasks, allow you to keep a library of reusable components and provide real-time preview of the generated documentation. -- **Domain-Specific Languages**: As its name indicates, [DSL](https://tools.openapis.org/categories/dsl)'s are API description languages tailored to specific development fields. A tool is then used to produce the OpenAPI document. A new language has to be learned, but, in return, extremely concise descriptions can be achieved. +- **Domain-Specific Languages**: As its name indicates, [DSL](https://tools.openapis.org/categories/dsl)'s are API description languages tailored to specific development fields. A tool is then used to produce the OpenAPI Description. A new language has to be learned, but, in return, extremely concise descriptions can be achieved. -- **Code Annotations**: Most programming languages allow you to _annotate_ the code, be it with specific syntax or with general code comments. These annotations, for example, can be used to extend a method signature with information regarding the API endpoint and HTTP method that lead to it. A tool can then parse the code annotations and generate OpenAPI documents automatically. This method fits very nicely with the code-first approach, so keep in mind the first advice given at the top of this page when using it (Use a Design-First Approach)... +- **Code Annotations**: Most programming languages allow you to _annotate_ the code, be it with specific syntax or with general code comments. These annotations, for example, can be used to extend a method signature with information regarding the API endpoint and HTTP method that lead to it. A tool can then parse the code annotations and generate OADs automatically. This method fits very nicely with the code-first approach, so keep in mind the first advice given at the top of this page when using it (Use a Design-First Approach)... -- **A Mix of All the Above**: It's perfectly possible to create the bulk of an OpenAPI document using an editor or DSL and then hand-tune the resulting file. Just be aware of the second advice above (Keep a Single Source of Truth): Once you modify a file **it becomes the source of truth** and the previous one should be discarded (maybe keep it as backup, but out of the sight and reach of children and newcomers to the project). +- **A Mix of All the Above**: It's perfectly possible to create the bulk of an OpenAPI Description using an editor or DSL and then hand-tune the resulting file. Just be aware of the second advice above (Keep a Single Source of Truth): Once you modify a file **it becomes the source of truth** and the previous one should be discarded (maybe keep it as backup, but out of the sight and reach of children and newcomers to the project). -## Working with Big Documents +## Describing Large APIs -This is a collection of small hints related to working with large API description documents. +This is a collection of small hints related to working with large OADs. - **Do not repeat yourself** (The DRY principle). If the same piece of YAML or JSON appears more than once in the document, it's time to move it to the `components` section and reference it from other places using `$ref` (See [Reusing Descriptions](specification/components). Not only will the resulting document be smaller but it will also be much easier to maintain). - Components can be referenced from other files, so you can even reuse them across different API documents! + Components can be referenced from other documents, so you can even reuse them across different API descriptions! -- **Split the document into several files**: Smaller files are easier to navigate, but too many of them are equally taxing. The key lies somewhere in the middle. +- **Split the description into several documents**: Smaller files are easier to navigate, but too many of them are equally taxing. The key lies somewhere in the middle. - A good rule of thumb is to use the natural hierarchy present in URLs to build your file structure. For example, put all routes starting with `/users` (like `/users` and `/users/{id}`) in the same file (think of it as a "sub-API"). + A good rule of thumb is to use the natural hierarchy present in URLs to build your directory structure. For example, put all routes starting with `/users` (like `/users` and `/users/{id}`) in the same file (think of it as a "sub-API"). Bear in mind that some tools might have issues with large files, whereas some other tools might not handle too many files gracefully. The solution will have to take your toolkit into account. diff --git a/index.md b/index.md index b8f1a1a..40234c6 100644 --- a/index.md +++ b/index.md @@ -7,15 +7,15 @@ nav_order: 1 # Getting started ## Intended Audience -This guide is directed at **HTTP-based API** designers and writers wishing to benefit from having their API formalized in an **OpenAPI Description document**. +This guide is directed at **HTTP-based API** designers and writers wishing to benefit from having their API formalized in an **OpenAPI Description** (**OAD**). Machine-readable API descriptions are ubiquitous nowadays and **OpenAPI** is **the most broadly adopted industry standard for describing new APIs**. It is therefore worth learning it and getting it right from the start. -These pages are a companion to the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0), helping the reader learn it and answering questions like "What is the best way to accomplish... ?" or "What is the purpose of... ?" that are naturally out of the scope of the specification. +These pages are a companion to the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) (OAS), helping the reader learn it and answering questions like "What is the best way to accomplish... ?" or "What is the purpose of... ?" that are naturally out of the scope of the specification. - If you are unsure if this guide is for you, read the next section below. - If you do not know what "API", "machine-readable description" or "OpenAPI" mean start by reading the [Introduction](introduction) chapter. -- If this is your first time writing an **OpenAPI Description document** read [The OpenAPI Specification explained](specification) chapter for step-by-step tutorials. +- If this is your first time writing an **OpenAPI Description** read [The OpenAPI Specification explained](specification) chapter for step-by-step tutorials. - If you already have **OpenAPI** experience but need help with a specific topic, take a look at the index of [The OpenAPI Specification explained](specification) chapter; it also includes advanced topics. - Finally, make sure you are aware of the recommended [Best Practices](best-practices) to take full advantage of **OpenAPI**! - And of course, you can always refer to the actual [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) for reference. @@ -36,6 +36,6 @@ On top of this, the **OpenAPI Specification** also provides you with: - **A non-proprietary format**: You have a say in the future direction of the Specification! - **The most developed tooling ecosystem**: As a direct result of the previous statement, OpenAPI offers a vast number of tools to work with it. Just take a quick look at [OpenAPI Tooling](https://tools.openapis.org). -- **A format readable by both machines and humans**: Even though writing **OpenAPI** documents by hand is not the most convenient way of doing it (See [Best Practices](best-practices)), they are plain text files which can be easily browsed in case something needs to be debugged. +- **A format readable by both machines and humans**: Even though writing OADs by hand is not the most convenient way of doing it (See [Best Practices](best-practices)), they are plain text files which can be easily browsed in case something needs to be debugged. So, choose your desired entry point from the list at the top of this page and start your journey! diff --git a/introduction.md b/introduction.md index 3127932..a962c4b 100644 --- a/introduction.md +++ b/introduction.md @@ -7,9 +7,9 @@ nav_order: 2 # Introduction -The **OpenAPI Specification** allows the description of a remote API accessible through HTTP or HTTP-like protocols. This chapter explains why this is a good thing and why it might interest you. +The **OpenAPI Specification** (**OAS**) allows the description of a remote API accessible through HTTP or HTTP-like protocols. This description, which may be stored as one or more documents (such as local files or HTTP-accessible network resources), is called an **OpenAPI Description** (**OAD**). This chapter explains why describing your API with an OAD is a good thing, and why it might interest you. -The concept of an "API" is described first and the advantages of describing APIs using a machine-readable format are introduced, followed by the benefits of using the OpenAPI format. In the last section, the evolution of API descriptions is put into perspective with a brief historical summary. +The concept of an "API" is described first and the advantages of describing APIs using a machine-readable format are introduced, followed by the benefits of using the OAS format. In the last section, the evolution of API descriptions is put into perspective with a brief historical summary. If you are already familiar with the benefits of machine-readable API descriptions and the OpenAPI in particular you may skip ahead to the next chapter, [The OpenAPI Specification explained](specification). @@ -33,7 +33,7 @@ Using APIs is an everyday practice in computer science since their benefits are Now, in order for all involved parties to adhere to the same API it has to be precisely defined. The next section describes how this has traditionally been achieved. -## API Definition Through Documentation +## API Description Through Documentation APIs are typically accompanied by a **reference guide**; a piece of literature explaining to a developer how to use the API. @@ -46,13 +46,13 @@ Unfortunately, everybody working on software development is familiar with one or In these cases, to find the information they require developers might have to read source code (if available), debug programs or analyze network traffic, which are gigantic **time sinks**. -Furthermore, errors in the usage of an API defined through its documentation cannot be discovered until runtime, which is another time sink. +Furthermore, errors in the usage of an API described only through documentation cannot be discovered until runtime, which is another time sink. The next section shows how some of these problems can be alleviated by specifying APIs in a format that automated tools can use. -## API Definition Through a Description File +## API Description Using the OAS -An **API description file** (sometimes called Contract) is a **machine-readable** specification of an API. It should strive to be as **complete**, and **fully-detailed** as possible, although absolute completeness is not usually a requirement. Also, just like legal contracts, the more **unambiguous** it is, the more useful it becomes. +An **API description file** (sometimes called _contract_) is a **machine-readable** specification of an API. It should strive to be as **complete**, and **fully-detailed** as possible, although absolute completeness is not usually a requirement. Also, just like legal contracts, the more **unambiguous** it is, the more useful it becomes. Its main advantage over documentation which only humans can read is that it enables **automated processing**, opening the door to the benefits listed at [the beginning of this guide](start-here). @@ -65,21 +65,21 @@ To name only another possibility, the API description file might include example For all the above reasons and many more it is highly advisable to use a machine-readable description when designing a new API. -Over the years several API description formats (called Specifications) emerged. The following section lists the benefits of **OpenAPI**, the most widely used specification when creating new APIs. +Over the years several API description formats (called _specifications_) emerged. The following section lists the benefits of **OpenAPI**, the most widely used specification when creating new APIs. ## The OpenAPI Specification -The OpenAPI Specification (**OAS**) is a **vendor neutral** description format for HTTP-based remote APIs. It was originally based on the Swagger 2.0 Specification, donated by SmartBear Software in 2015. +The OpenAPI Specification (**OAS**) is a **vendor-neutral** description format for HTTP-based remote APIs. It was originally based on the Swagger 2.0 Specification, donated by SmartBear Software in 2015. Currently, the OAS is maintained, evolved and promoted by the OpenAPI Initiative (**OAI**), a consortium of industry experts with an open governance structure under the Linux Foundation umbrella. This means all meetings and decisions are public and changes to the OAS can be proposed and discussed by anyone. -This openness has encouraged the creation of a vast amount of tools (take a look at [the OpenAPI tools list](https://tools.openapis.org/), for example) which perfectly showcase the power of open, machine-readable API descriptions (called **documents** in OpenAPI). +This openness has encouraged the creation of a vast amount of tools (take a look at [the OpenAPI tools list](https://tools.openapis.org/), for example) which perfectly showcase the power of open, machine-readable API descriptions such as OADs. It's probably because of the amount of tools available when working with OpenAPI that it has become **the most broadly adopted industry standard for describing modern APIs**. -It is also worth mentioning that the OAS does not aim at being able to describe **every possible API**, since doing so would require a rather large and unwieldy specification. Instead, it tries to **describe efficiently the most common use cases**. Still, the benefits provided by OpenAPI are so numerous that it is usually worth it to design your API so it can be fully defined using the OAS. +It is also worth mentioning that the OAS does not aim at being able to describe **every possible API**, since doing so would require a rather large and unwieldy specification. Instead, it tries to **describe efficiently the most common use cases**. Still, the benefits provided by OpenAPI are so numerous that it is usually worth it to design your API so it can be fully described using the OAS. -If parts of your API cannot be described using the OAS, and they cannot be redesigned, they can still be left out of the OAS document: OpenAPI lists operations that you can do, but it does not assert anything regarding operations not in the OAS document. +If parts of your API cannot be described using the OAS, and they cannot be redesigned, they can still be left out of the OAD: OpenAPI lists operations that you can do, but it does not assert anything regarding operations not in the OAD. Finally, OpenAPI can describe APIs based on the HTTP protocol (like RESTful ones) but also APIs based on **HTTP-like protocols** like CoAP (Constrained Application Protocol) or WebSockets. This allows OpenAPI to be used in resource-restricted scenarios like IoT (Internet of Things), for example. @@ -99,6 +99,6 @@ Later on, the Internet arrived and with it appeared **remote APIs**. HTTP-based Machine-readable API descriptions (including **OpenAPI**) were then invented to bring to remote APIs the same degree of robustness that method signatures brought to local APIs. Tools do exist now which check that requests are made in the correct format, or even ensure it by generating the request code themselves. -The benefits delivered by machine-readable descriptions of remote APIs, though, have far surpassed those of method signatures. For instance, OpenAPI can attach examples and notes to most API sections, to complement the automatically-generated documents, or reuse parts of the description to make the whole file leaner. +The benefits delivered by machine-readable descriptions of remote APIs, though, have far surpassed those of method signatures. For instance, OpenAPI can attach examples and notes to most API sections, to complement the automatically-generated documentation, or reuse parts of the description to make the whole file leaner. Learn about all these capabilities and more in the next chapter, [The OpenAPI Specification explained](specification). diff --git a/specification/components.md b/specification/components.md index 107441c..bea27fd 100644 --- a/specification/components.md +++ b/specification/components.md @@ -7,19 +7,19 @@ nav_order: 5 # Reusing Descriptions -As is often the case, the example built through the previous pages has grown too large to be easily manageable. This page introduces a mechanism to remove redundancy from an OpenAPI document by reusing portions of it. +As is often the case, the example built through the previous pages has grown too large to be easily manageable. This page introduces a mechanism to remove redundancy from an OpenAPI Description (OAD) by reusing portions of it. ## The Components Object The [Components Object](https://spec.openapis.org/oas/v3.1.0#components-object), -accessible through the `components` field in the root [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), contains definitions for objects to be reused in other parts of the document. +accessible through the `components` field in the root [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), contains definitions for objects to be reused in other parts of the description.
-
The OpenAPI Object is explained in the Structure of an OpenAPI Document page.
The Schema Object is explained in the Content of Message Bodies page.
The Response Object is explained in the API Endpoints page.
The Parameter Object is explained in the Parameters and Payload of an Operation page.
+
The OpenAPI Object is explained in the Structure of an OpenAPI Description page.
The Schema Object is explained in the Content of Message Bodies page.
The Response Object is explained in the API Endpoints page.
The Parameter Object is explained in the Parameters and Payload of an Operation page.
-Most objects in an OpenAPI document can be replaced by a **reference** to a **component**, drastically reducing the document's size and maintenance cost (just like methods do in programming languages). +Most objects in an OAD can be replaced by a **reference** to a **component**, drastically reducing the OAD's size and maintenance cost (just like methods do in programming languages). Not all objects can be referenced, though, only those listed as fields of the [Components Object](https://spec.openapis.org/oas/v3.1.0#components-object) like `schemas`, `responses` and `parameters` to name a few. @@ -101,9 +101,9 @@ The complete [Tic Tac Toe sample API](/examples/tictactoe.yaml) (not included he ## Summary -Whenever the same piece of JSON or YAML is repeated in an OpenAPI document, it is probably worth converting it into a component and referencing it everywhere else. +Whenever the same piece of JSON or YAML is repeated in an OAD, it is probably worth converting it into a component and referencing it everywhere else. -Furthermore, [Reference Objects](https://spec.openapis.org/oas/v3.1.0#reference-object) allow splitting a document into several files to keep them organized and their individual size manageable. +Furthermore, [Reference Objects](https://spec.openapis.org/oas/v3.1.0#reference-object) allow splitting a description into several documents to keep them organized and their individual size manageable. This page has shown that: @@ -111,4 +111,4 @@ This page has shown that: - Components can be referenced from any place where an object of the same type is expected using `$ref`. - References are actually URIs so they are very flexible. -[The next page](docs) explains how to include documentation and examples in an OpenAPI document. +[The next page](docs) explains how to include documentation and examples in an OpenAPI Description. diff --git a/specification/content.md b/specification/content.md index b72a1c8..b8a4088 100644 --- a/specification/content.md +++ b/specification/content.md @@ -158,7 +158,7 @@ The response contains an object is JSON format with two fields: - `winner` is a string with only three possible values: `.`, `X` and `O`. - `board` is a 3-element array where each item is another 3-element array, effectively building a 3x3 square matrix. Each element in the matrix is a string with only three possible values: `.`, `X` and `O`. -This document is starting to grow too big and complex. The [Reusing Descriptions](components) page explains how to name sections of an OpenAPI document in order to reuse them (like the strings with three options above, which appear twice). +This part of our description is starting to grow too big and complex. The details of the response schema take up a lot of space, obscuring the request/response structure. The deep nesting also makes the schema harder to spot within the larger object. The [Reusing Descriptions](components) page explains how to name sections of an OpenAPI Description (OAD) in order to reuse them (like the strings with three options above, which appear twice). ## Summary diff --git a/specification/docs.md b/specification/docs.md index 240e19c..940e8a0 100644 --- a/specification/docs.md +++ b/specification/docs.md @@ -7,7 +7,7 @@ nav_order: 6 # Providing Documentation and Examples -Besides machine-readable descriptions, an OpenAPI document can also include traditional documentation meant to be read by developers. Automatic documentation generators can then merge both and produce comprehensive, nicely-structured reference guides, for example. +Besides machine-readable descriptions, an OpenAPI Description (OAD) can also include traditional documentation meant to be read by developers. Automatic documentation generators can then merge both and produce comprehensive, nicely-structured reference guides, for example. This page shows how to take full advantage of special documentation capabilities in OpenAPI like markdown syntax or example objects. @@ -15,7 +15,7 @@ This page shows how to take full advantage of special documentation capabilities Almost every object in the OpenAPI Specification accepts a `description` field which can provide additional information for developers, beyond what can be automatically generated from the API descriptions. -For instance, a parameter's name, type and valid range of values are already present in the API definition. The `description` field can complement this information by explaining the **purpose** of this parameter, the **effect of each value** or possible **interactions** with other parameters: +For instance, a parameter's name, type and valid range of values are already present in the API description. The `description` field can complement this information by explaining the **purpose** of this parameter, the **effect of each value** or possible **interactions** with other parameters: ```yaml paths: diff --git a/specification/index.md b/specification/index.md index d5e3d40..0c705d3 100644 --- a/specification/index.md +++ b/specification/index.md @@ -10,9 +10,9 @@ has_toc: false The [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) is the ultimate source of knowledge regarding this API description format. However, its length is daunting to newcomers and makes it hard for experienced users to find specific bits of information. This chapter provides a soft landing for readers not yet familiar with OpenAPI and is organized by topic, simplifying browsing. -The following pages introduce the syntax and structure of an OpenAPI document, its main building blocks and a minimal API document. Afterwards, the different blocks are detailed, starting from the most common and progressing towards advanced ones. +The following pages introduce the syntax and structure of an OpenAPI Description (OAD), its main building blocks and a minimal API description. Afterwards, the different blocks are detailed, starting from the most common and progressing towards advanced ones. -- [Structure of an OpenAPI Document](structure): JSON, YAML, `openapi` and `info` +- [Structure of an OpenAPI Description](structure): JSON, YAML, `openapi` and `info` - [API Endpoints](paths): `paths` and `responses`. - [Content of Message Bodies](content): `content` and `schema`. - [Parameters and Payload of an Operation](parameters): `parameters` and `requestBody`. diff --git a/specification/parameters.md b/specification/parameters.md index f227d82..dbf0908 100644 --- a/specification/parameters.md +++ b/specification/parameters.md @@ -95,7 +95,7 @@ In more advanced scenarios the `content` field can be used instead. It provides ### Parameter Serialization Control -The `style` field defines how a parameter is to be serialized and its effect depends on the **type** of the parameter. The resulting matrix is therefore rather complex and can be consulted in the [Parameter Object](https://spec.openapis.org/oas/v3.1.0#style-examples) specification page. +The `style` field describes how a parameter is to be serialized and its effect depends on the **type** of the parameter. The resulting matrix is therefore rather complex and can be consulted in the [Parameter Object](https://spec.openapis.org/oas/v3.1.0#style-examples) specification page. The tables given below exemplify the most common styles `simple`, `form`, `label`, and `matrix`: @@ -195,11 +195,11 @@ paths: ... ``` -- Both operations (`get` and `put`) have the same parameters, since they are defined at the Path Item level. +- Both operations (`get` and `put`) have the same parameters, since they are described at the Path Item level. - The parameters are two integers, named `row` and `column` which are located in the path of the operation. This matches the path name which contains `{row}` and `{column}`. - The `put` operation, additionally, must provide a request body which must be one of the three provided strings: `.`, `X` and `O`. -The complete [Tic Tac Toe sample API](/examples/tictactoe.yaml) does not look exactly like the above snippet because it reuses portions of the document to remove redundancy. This technique is explained in the [Reusing Descriptions](components) page. +The complete [Tic Tac Toe sample API](/examples/tictactoe.yaml) does not look exactly like the above snippet because it reuses portions of the description to remove redundancy. This technique is explained in the [Reusing Descriptions](components) page. ## Summary @@ -209,4 +209,4 @@ This page has shown: - Parameters can be located in different places (`path`, `query`, `headers`) and their content (`schema`) and serialization (`style`) is highly customizable. - The request body is specified, much like responses are, using the `content` field. -[The next page](components) explains how to reuse portions of an OpenAPI document to remove redundancy, reducing file size and maintenance cost. +[The next page](components) explains how to reuse portions of an OpenAPI Description to remove redundancy, reducing file size and maintenance cost. diff --git a/specification/paths.md b/specification/paths.md index c056a1e..175af00 100644 --- a/specification/paths.md +++ b/specification/paths.md @@ -7,7 +7,7 @@ nav_order: 2 # API Endpoints -[The previous page](structure) showed the minimal structure of an OpenAPI document but did not add any operation to the API. This page explains how to do it. +[The previous page](structure) showed the minimal structure of an OpenAPI Description (OAD) but did not add any operation to the API. This page explains how to do it. ## The Endpoints list @@ -15,7 +15,7 @@ API Endpoints (also called Operations or Routes) are called **Paths** in the OAS
-
The OpenAPI Object is explained in the Structure of an OpenAPI Document page.
+
The OpenAPI Object is explained in the Structure of an OpenAPI Description page.
Every field in the [Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object) is a [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) describing one API endpoint. Fields are used instead of an Array because they enforce endpoint name uniqueness at the syntax level (any JSON or YAML parser can detect mistakes without requiring an OpenAPI validator). @@ -104,7 +104,7 @@ paths: ## Tic Tac Toe Example -Here's a fragment of the example, containing only the objects that have been defined so far in the guide. At this point the reader should be able to understand every line of this snippet. +Here's a fragment of the example, containing only the objects that have been described so far in the guide. At this point the reader should be able to understand every line of this snippet. ```yaml openapi: 3.1.0 @@ -127,7 +127,7 @@ paths: ... ``` -The complete document can be found in the [Tic Tac Toe sample API](/examples/tictactoe.yaml). +The complete OpenAPI Description can be found in the [Tic Tac Toe sample API](/examples/tictactoe.yaml). ## Summary diff --git a/specification/servers.md b/specification/servers.md index 9b1d4fa..37e03e4 100644 --- a/specification/servers.md +++ b/specification/servers.md @@ -15,7 +15,7 @@ The [Server Object](https://spec.openapis.org/oas/v3.1.0#server-object) provides
-
The edges marked with an asterisk are arrays.
The OpenAPI Object is explained in the Structure of an OpenAPI Document page.
The Paths, Path Item and Operation Objects are explained in the API Endpoints page.
+
The edges marked with an asterisk are arrays.
The OpenAPI Object is explained in the Structure of an OpenAPI Description page.
The Paths, Path Item and Operation Objects are explained in the API Endpoints page.
Each element in a `servers` array is a [Server Object](https://spec.openapis.org/oas/v3.1.0#server-object) providing, at least, a `url` field with the base URL for that server. An optional `description` aids in keeping server lists organized: @@ -57,13 +57,13 @@ paths: GET requests to the `/users` endpoint are served from `https://server2.com` and **not** from `https://server1.com`. > **NOTE:** -> When providing multiple servers in an OpenAPI document keep in mind that they should all **provide the same API** (since they are being listed in the same document). +> When providing multiple servers in an OpenAPI Description (OAD) keep in mind that they should all **provide the same API** (since they are being listed in the same API description). > -> If the servers are used for different environments (for example Testing and Production), chances are that their APIs will be different and describing them in a single document will be complicated. +> If the servers are used for different environments (for example Testing and Production), chances are that their APIs will be different and describing them in a single OAD will be complicated. > -> In these cases it is probably better to use different documents, and even different API versions. Read the [Reusing Descriptions](components) page to learn how to avoid code duplication and maintenance costs in these scenarios. +> In these cases it is probably better to use different OADs, and even different API versions. Read the [Reusing Descriptions](components) page to learn how to avoid code duplication and maintenance costs in these scenarios. -Conversely, if no servers are provided, it is assumed that all API endpoints are relative to the location where the OpenAPI document is being served. +Conversely, if no servers are provided, it is assumed that all API endpoints are relative to the location where the OpenAPI Description document is being served. Be aware that if your OAD is split across multiple documents, each endpoint id assumed to be relative to the document in which it is described. Describing a server ensures that your endpoints are the same regardless of how your OAD is organized. Finally, the server URLs can contain variable portions, as shown next. diff --git a/specification/structure.md b/specification/structure.md index c5ac8e4..f3c0f96 100644 --- a/specification/structure.md +++ b/specification/structure.md @@ -1,19 +1,19 @@ --- layout: default -title: Structure of an OpenAPI Document +title: Structure of an OpenAPI Description parent: The OpenAPI Specification Explained nav_order: 1 --- -# Structure of an OpenAPI Document +# Structure of an OpenAPI Description -An OpenAPI document describes an HTTP-like API in one or more machine-readable files. This page describes the syntax of these files and the minimal structure they must contain. +An OpenAPI Description (OAD) describes an HTTP-like API in one or more machine-readable documents (files or network resources). This page describes the syntax of these documents and the minimal structure they must contain. -## Document Syntax +## OpenAPI Description Syntax -An OpenAPI document is a text file, commonly called `openapi.json` or `openapi.yaml`, representing a [JSON](https://en.wikipedia.org/wiki/JSON) object, in either JSON or [YAML](https://en.wikipedia.org/wiki/YAML) format. This file is called the **root document** and it can be split into multiple JSON or YAML files, for clarity. +OpenAPI Descriptions are written as one or more text documents, commonly called `openapi.json` or `openapi.yaml`. Each document represents a [JSON](https://en.wikipedia.org/wiki/JSON) object, in either JSON or [YAML](https://en.wikipedia.org/wiki/YAML) format. **References** are used to link parts of the JSON object(s) to each other, and this linked structure is the complete OpenAPI Description. Parsing begins with an [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), and the document containing that object is known as the **entry document**. -This section very briefly describes these two formats and compares them. +This section very briefly describes and compares the JSON and YAML data formats. JSON can represent **Numbers**, **Strings**, **Booleans**, **`null` values**, **Arrays** and **Objects**. An array is an ordered list of values which can have different types. An object (also called a Map) is a collection of name-value pairs where the names (also called Keys or Fields) are unique within the object and the values can have any of the supported types (including other objects or arrays). @@ -71,18 +71,18 @@ Finally, object field names are case-sensitive: `openapi` is not the same thing > **NOTE:** > Ellipses (...) are used throughout this guide to indicate an incomplete code snippet. Ellipses are not part of JSON or YAML. -## Minimal Document Structure +## Minimal OpenAPI Description Structure -To be entirely precise, an OpenAPI document is a single JSON object containing fields adhering to the structure defined in the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) (OAS). +To be entirely precise, a minimal OpenAPI Description (OAD) is a single JSON object containing fields adhering to the structure defined in the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) (OAS). The OAS structure is long and complex so this section just describes the minimal set of fields it must contain, while following pages give more details about specific objects. The [OpenAPI Map](https://openapi-map.apihandyman.io/) is a nice visual tool that can help familiarize the reader with this long specification. -The root object in any OpenAPI document is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object) and only two of its fields are mandatory: `openapi`, and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required. +The root object in any OpenAPI Description is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), and only two of its fields are mandatory: `openapi` and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required. -* `openapi` (**string**): This indicates the version of the OAS this document is using, e.g. "3.1.0". Using this field tools can check that the document correctly adheres to the spec. +* `openapi` (**string**): This indicates the version of the OAS this OAD is using, e.g. "3.1.0". Using this field tools can check that the description correctly adheres to the specification. * `info` ([Info Object](https://spec.openapis.org/oas/v3.1.0#info-object)): This provides general information about the API (like its description, author and contact information) but the only mandatory fields are `title` and `version`. * `title` (**string**): A human-readable name for the API, like "GitHub REST API", useful to keep API collections organized. - * `version` (**string**): Indicates the version **of the API document** (not to be confused with the OAS version above). Tools can use this field to generate code that ensures that clients and servers are interacting through the same version of the API, for example. + * `version` (**string**): Indicates the version **of the API description** (not to be confused with the OAS version above). Tools can use this field to generate code that ensures that clients and servers are interacting through the same version of the API, for example. * `paths` ([Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object)): This describes all the **endpoints** of the API, including their parameters and all possible server responses. Server and client code can be generated from this description, along with its documentation.
@@ -90,12 +90,12 @@ The root object in any OpenAPI document is the [OpenAPI Object](https://spec.ope
Diagrams are used in this guide to show the relationship between the different objects.
-Here's an example of a minimal OpenAPI document: +Here's an example of a minimal OpenAPI Description: ```yaml openapi: 3.1.0 info: - title: A minimal OpenAPI document + title: A minimal OpenAPI Description version: 0.0.1 paths: {} # No endpoints defined ``` @@ -106,8 +106,8 @@ This API is not very useful because it **defines no operations** (it has no endp This page has shown that: -* The syntax (language) used to write OpenAPI documents can be **JSON**, **YAML** or **both**. -* An OpenAPI document is a JSON object including the fields described in the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0). -* Every OpenAPI document must contain a root object with at least the fields `openapi`, and `info`, and either `paths`, `components` or `webhooks`. +* The syntax (language) used to write OpenAPI Descriptions can be **JSON**, **YAML** or **both**. +* An OpenAPI Descriptions is a JSON object including the fields described in the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0). +* Every OpenAPI Descriptions must contain an OpenAPI Object with at least the fields `openapi`, and `info`, and either `paths`, `components` or `webhooks`. [The following page](paths) describes the contents of the `paths` field so endpoints can be added to the above minimal snippet.