Understanding Swagger

• What is Swagger?
• How does Apigee 127 use Swagger?
• Help me with YAML

What is Swagger?

Swagger™ is a specification and framework implementation for describing, producing, consuming, and visualizing RESTful web services.

To read more about Swagger, refer to:

• The Swagger website
• Swagger on GitHub

How does Apigee 127 use Swagger?

The Swagger Editor for Apigee 127 lets you design your API specification and preview its documentation for your Apigee 127 API. This editor is part of Apigee 127, and it is installed with Apigee 127.

Use this editor to configure the swagger.yaml configuration file. A basic version of the file is provisioned with every new Apigee 127 project, and lives in <project_root>/api/swagger/swagger.yaml. It conforms to the Swagger 2.0 specification.

Behind the scenes, Apigee 127 Swagger middleware validates and processes the Swagger configuration file, and routes API operation endpoints to controller files. All you need to do is implement your custom API controller logic.

Try it:

1. a127 project create test-project
2. cd test-project
3. a127 project edit

The Swagger editor for Apigee 127:

Help me with YAML

YAML is a data serialization/representation standard. If you're new to YAML, check out www.yaml.org. Another excellent introduction is the Uncyclopedia YAML entry.

YAML is intended to be easy for humans to read. Every Apigee 127 project includes a Swagger 2.0 compliant configuration file that is written in YAML.

Next step

Now that you know a little about Swagger, go to the next topic "The Swagger specification file" for details on the elements and extensions you need to know about to build an Apigee 127 model.