Learn Swagger and the Open API Specification
The Open API Specification (often called “Swagger”) is currently the most popular way to create definitions of RESTful APIs. With these definitions, you can create sophisticated, autogenerated documentation, generate SDKs in several languages, and do automated testing. Swagger is a set of open source tools that use these Open API Specification definition files.
This class is for people in the software industry who are fairly technical, but are not software developers: for example, project managers, API product managers, and technical writers. It assumes that you understand REST and JSON, but that’s about all. It is meant to be for people who are new to the Open API Specification and Swagger, rather than for experts. It covers:
What you can do with Open API Specification (OAS) files
The YAML file format
How to create an OAS file
How to specify security
How to add documentation
How to write an OAS file in JSON
Alternatives to Swagger and OAS
This class does not cover:
How to set up Swagger on your own server
How to modify Swagger open source code
In addition to videos, this course contains 8 hands-on exercises that lead you step-by-step in creating an API definition file, including a final project where you create a file from scratch using documentation from an actual commercial API. It also contains a document with resources on learning more about OAS, Swagger, and alternatives.
In addition to the video lectures, except to spend at least 4 hours doing the exercises. These exercises are key to understanding Swagger and OAS.
Note: The course describes OAS 2. A newer version, OAS 3, has become available recently. At some point the course will be updated to reflect OAS 3.
Introduction
Covers:
- API Definitions
- What is a REST API?
- Prerequisites
- Swagger
- The Open API Initiative
- Course Overview
Covers:
- What’s an API Definition File?
- Anatomy of an API Request
- What’s in an API Definition File?
- Getting Information to create an API Definition File
- How YAML is used with the Open API Specification
- What is YAML?
- Rules of YAML
Answer these questions about the YAML format.
Open API Specification
- What applies to the entire API
- What applies to a simple request
- Path, method, query and parameters, headers
- Using the Swagger editor
Answer these questions about the Open API Specification format.
Covers:
- What is a schema?
- References
- Request bodies
- Response bodies
Answer these questions about schemas.
Covers:
- Security
- Error Conditions
- Content types (JSON, JPEG, etc.)
- Operation IDs
Answer these questions about the Open API Specification
Covers:
- What autogenerated documentation is
- How autogenerated documentation looks
- How to add description tags
Tools and Alternatives
- Swagger editor
- Swagger CodeGen
- Swagger UI (Autogenerated documentation)
- Core tooling
- SwaggerHub
- Why JSON over YAML?
- How to construct JSON OAS files
- Alternatives to Swagger
- DapperDox, Swagger UI variants, ReadMe.io, StopLight.io
- Alternatives to OAS
- RAML, API Blueprint
- Resources
Links to resources on Swagger and alternatives.
