Open API is a great standard. I created a presentation to help people understand Open API and Swagger and I provided some examples to get started. This particular REST API had an accompanying Java Spring Boot project.

Fun With Swagger

I hosted a workshop to promote Open API (Swagger).

One of the examples we used during the workshop.

Contract Driven Development

Design First vs Code First

• Design First: Start with design, then transition to code.
• Code First: Generate Swagger from existing code.
• Goal: Generate as much documentation as possible using Open API 3.
• Open API 3 Specification
• Design First vs Code First API Development

Main Issues with Round Trip Process

• Generating code from Swagger is challenging.
• Generating Swagger from code is easier.
• Swagger authoring can be cumbersome.

Benefits of Swagger

• Forms the context and contract between components (e.g., UI to Backend, Customers consuming your REST API).
• Helps to form standards.
• Enables generation and display of APIs from documentation.
• Allows easy generation of mock servers.

Symbiotic Tools

• POSTMAN
• Newman: Newman GitHub

Demo Time

• Demonstration of creating Swagger files.

Generate Swagger from Code

• Java Spring:
• Spring Fox
• Jax RS / Jersey
• swagger-jaxrs
• Generate Swagger
• ExpressJS:
• Flask Swagger
• Note: None are great at round trip authoring.

Generate During the Build

• Swagger Gradle Plugin
• Swagger Maven Plugin

Future Plans

• Save all Swagger files to a common location.
• Add the Open API plugin to Confluence and host API documents there.

Summary

• Overview of Swagger.
• How to create Swagger.
• Using Swagger Hub.
• Creating contracts between layers/components.
• Transition from Design First to Code First.
• Instrumenting your API to generate Swagger.
• Adding Swagger to the Accelerator collective.