API documentation is key, but "sometimes developers and documentation just don’t mix." Developer eXperience is giving developers what they need to succeed, and OpenAPI specification (OAS) can help in that.
Is a good choice for describing RESTful APIs in a machine readable-way,
Enhances DX: an API spec is reusable and this can be super powerful,
Is a result of teamwork: product owners, writers, engineers should co-write it.
New APIs or existing ones?
Retrofitting an existing API into OAS is not always easy, but it’s doable and valuable,
Spec-first API design: cheaper and effective way to design a new API starting on actual development, with all the stakeholders included in the conversation (product owner, writer, engineer).
Anatomy of OAS
Tree structure, like a ToC with chapter headings, subheadings,
Json or yaml file holds the description,
Add (standardized) metadata now for discoverability in a future API ecosystem ,
Lots of APIs? Group and re-group using your tagging system.
ReDoc: render the yaml to your branding, the front-end is entirely separate from the spec content,
Source control! Commit the description file when it's working,
See further Lorna Jane's presentation on editing-, validation- and preview tools.
"The initial discussion to design a new API, even before starting developing it, is a very cheap stage of the process and can save lots of costly pains later if you include all the stakeholders in the conversation" -- #apithedocs London is @medjawii talking about APIs in banking and their developer portals pic.twitter.com/46d0DBiBkE