Lightning Talk: Skip the Grunt Work, Document Your APIs with Swagger

[ryoarmanda]

One of the major pain points in documenting APIs is the obligation to maintain two separate things at once, the codebase and the documentation, which traditionally is created by hand. It shouldn't be this way.

Swagger (now renamed as OpenAPI) is a specification for describing REST APIs. With an OpenAPI spec file, developers can generate documentation page accessible for both developers and non-developers through Swagger UI. This spec file can either be created by hand, or generated through comments by using integration libraries specific to the language of choice. It's wide adoption, established ecosystem, and community-driven integrations makes it a perfect choice for quick and easy API documentation.

Round A:

Topic:
Utilize Swagger/OpenAPI Specification to Document APIs Easily

WIIFY:
Learn how documentation can be made easy (and shouldn't be that hard) with Swagger/OpenAPI.

Key Points:

1. OpenAPI is an industry-recognized specification adopted by key companies.
2. OpenAPI has an established tooling ecosystem that can produce documentation pages with just a spec file.
3. Developers can document right from code with the use of community-driven OpenAPI integrations.

Impact:

1. Know: What is the OpenAPI specification and its benefits
2. Believe: API documentation can be made easy with the use of OpenAPI
3. Do: Use OpenAPI in current and future projects for API documentation

Slides:
https://docs.google.com/presentation/d/1rI9kZfVIiUywtX453ARydnc84eTKHYinQ_HSPS4pk2k/edit?usp=sharing