Google Cloud Endpoints supports APIs that are described using version 2.0 of the OpenAPI Specification. Your API can be implemented using any publicly available REST framework such as Django or Jersey. You describe your API in a JSON or YAML file referred to as an OpenAPI configuration file. This page describes some of the benefits to using OpenAPI, shows a basic OpenAPI configuration file, and provides additional information to help you get started with OpenAPI.
One of the primary benefits to using OpenAPI is for documentation; once you have an OpenAPI configuration file for your API, it is easy to add the Swagger UI to your project as an interactive documentation tool. See Adding Swagger UI to your project for a brief guide.
There other benefits to using OpenAPI. For example, you can:
- Generate client libraries in dozens of languages.
- Generate server stubs.
- Use projects to verify your conformance and to generate samples.
Basic Structure of an OpenAPI Configuration File
An OpenAPI configuration file describes the surface of your REST API, and defines information such as:
- The name and description of the API.
- The individual endpoints (paths) in the API.
- How the callers are authenticated.
If you are new to OpenAPI, the complete OpenAPI Specification can be a bit daunting. To get started, take a look at the Swagger Basic Structure website, which provides a sample OpenAPI configuration file (also referred to as a Swagger specification) and briefly explains each section of the file. The OpenAPI configuration file from the Cloud Endpoints Quickstart illustrates this basic structure:
swagger: "2.0" info: title: "Airport Codes" description: "Get the name of an airport from its three-letter IATA code." version: "1.0.0" # This field will be replaced by the deploy_api.sh script. host: "YOUR-PROJECT-ID.appspot.com" schemes: - "https" paths: "/airportName": get: description: "Get the airport name for a given IATA code." operationId: "airportName" parameters: - name: iataCode in: query required: true type: string responses: 200: description: "Success." schema: type: string 400: description: "The IATA code is invalid or missing."
In addition to the basic structure, the
openapi.yaml file from the sample
code used in the tutorials illustrates:
- How to configure a path to use an API key.
- Various security schemes for authentication.
- OpenAPI extensions available for Cloud Endpoints APIs.
Generating an OpenAPI Configuration File
Depending on what language you are using, you may be able to generate the configuration file. In Java, there are open source projects for both Jersey and Spring that can generate a configuration file from annotations. There is also a Maven plugin. For Python users, flask-swagger may be an interesting project, and swagger-node-express for Node developers.
The OpenAPI community is continually developing tools to help in the composition (and, for some languages, automatic generation) of the OpenAPI configuration file. See the Swagger website for a complete list of tools and integrations.