In the Design phase, you define the requirements for your API. As an API designer, you plan the services you'd like to expose to consumers, and design RESTful APIs to access those services. You create an OpenAPI Specification in an easy-to-read JSON or YAML format to capture your API requirements.
The following sections provide more information about OpenAPI Specifications and the role they play in the lifecycle of your API.
What is an OpenAPI specification?
"The Open API Initiative (OAI) is focused on creating, evolving and promoting a vendor neutral API Description Format based on the Swagger Specification." For more information about the Open API Initiative, see https://openapis.org.
An OpenAPI Specification uses a standard format to describe a RESTful API. Written in either JSON or YAML format, an OpenAPI Specification is machine readable, but is also easy for humans to read and understand. The specification describes elements of an API such as its base path, paths and verbs, headers, query parameters, content types, response models, and more. In addition, an OpenAPI Specification is commonly used to generate API documentation.
Here's a fragment from an OpenAPI Specification that describes Apigee's simple hello world sample. For more information, view the specification in GitHub.
openapi: 3.0.0 info: description: OpenAPI Specification for the Apigee mock target service endpoint. version: 1.0.0 title: Mock Target API paths: /: get: summary: View personalized greeting operationId: View a personalized greeting description: View a personalized greeting for the specified or guest user. parameters: - name: user in: query description: Your user name. required: false schema: type: string responses: "200": description: Success /help: get: summary: Get help operationId: Get help description: View help information about available resources in HTML format. responses: "200": description: Success ...
Many excellent sources of information about OpenAPI Specifications exist. A good place to start is the Open API Initiative site, where you'll find overviews, blogs, and links to the OpenAPI Specifications. Refer to the specifications for detailed descriptions of the schema elements and data types.
There are a number of JSON and YAML example specifications that you can download from the
OpenAPI Specification repository.
What happens if I modify a specification?
Each OpenAPI Specification serves as the source of truth throughout the API lifecycle. The same specification is used at each phase in the API lifecycle, from development to publishing to monitoring.
When you edit or delete an OpenAPI Specification, it has impact down the line:
- If you edit a specification, you need to manually edit the related artifacts including the API proxy and any API products that expose its resources, and regenerate the API reference documentation to reflect the changes implemented in the specification.
- If you delete a specification, you need to manually delete the related artifacts including the API proxy and edit any API products to delete related resources, and regenerate the API reference documentation to reflect the removal of the specification and its resources.
What happens when I create an API proxy from an OpenAPI Specification?
You can create your API proxies from your OpenAPI Specifications. In just a few clicks, you'll have an API proxy with the paths, parameters, conditional flows, and target endpoints generated automatically. Then, you can add features such as OAuth security, rate limiting, and caching.
You can create an API proxy from an OpenAPI Specification using the Create Proxy Wizard, as described in Using OpenAPI Specifications to generate proxies. For a hands-on experience, step through the Create an API proxy from an OpenAPI Specification tutorial.
When you publish your API, you take a snapshot of the OpenAPI Specification to generate API reference documentation. That snapshot represents a specific version of the specification.