Understanding Swagger

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

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.

Note: The editor is served locally and automatically saves your work as you edit. In addition, if the project is running (a127 project start), it is automatically restarted each time the editor saves. Just be careful if you kill the editor, that you do not lose unsaved work.

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 Wikipedia 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

For a more detailed look the Apigee-127 Swagger configurations, see "The Swagger specification file".