Going to Infinity and Beyond Documentation with OpenAPI Specification (Longhorn PHP Edition)

A presentation at Longhorn PHP in in Austin, TX, USA by Taylor Barnett

Going to Infinity and Beyond Documentation with OpenAPI Specification

Going to Infinity and Beyond Documentation with OpenAPI Specification

Single Source of Truth

Single Source of Truth

So you've built an API...

So you've built an API...

What is the OpenAPI Specification? (formerly known as Swagger)

What is the OpenAPI Specification? (formerly known as Swagger)

Standard, structured approach for describing REST APIs that is both human and machine readable

Standard, structured approach for describing REST APIs that is both human and machine readable

An OpenAPI document looks like:

An OpenAPI document looks like:

Lead Community Engineer at Stoplight

Lead Community Engineer at Stoplight

Hidden OpenAPI Benefits

Hidden OpenAPI Benefits

It is NOT just for API References

It is NOT just for API References

More than a technical representation

More than a technical representation

Tool for Collaboration

Tool for Collaboration

Simplifies Standardizes

Simplifies Standardizes

Having an OpenAPI Specification (OAS) is a useful document for numerous reasons. The most common being the ease of generating API reference documentation, but it overshadows some additional benefits that you can gain from adopting the OpenAPI Specification. This talk will delve into the hidden value of the OpenAPI Specification, and how you can employ it to your advantage. Some of the ideas that we will explore are:

– What are the lesser known benefits of using OAS to build API docs – What is a single source of truth in an API – How OAS gives us a way to breakdown APIs and helps us improve communication around HTTP – How design-first APIs, mocking, and testing with OAS can create better developer experiences through feedback cycles – How OAS creates a structured document for collaboration between teams and other ways OAS can increase collaboration throughout the API design process

Attendees will leave the talk having a better grasp of how the OpenAPI Specifications can fit into their workflow, including different PHP and language-neutral tools, and how they can leverage it to improve their API design and developer experience processes.

Resources

The following resources were mentioned during the presentation or are useful additional information.

Buzz and feedback

Here’s what was said about this presentation on social media.