This document discusses the challenges of writing API documentation and how OpenAPI specifications and tools can help address these challenges. It notes that while no one enjoys writing API docs, everyone wants good documentation. It then outlines how OpenAPI specifications can be used to generate documentation, mocks, tests, and client code to establish a "spec first" workflow where the specification acts as a single source of truth and contract between teams. This helps ensure documentation and clients remain in sync as the API evolves.

1. WHO HAS EVER
READ
AN API DOC?

2. WHO HAS EVER
WRITTEN
AN API DOC?

3. WHO HAS EVER
LOVED WRITING
AN API DOC?

4. Mehdi Lahmam
@mehlah
4

5. NO ONE LOVES WRITING
API DOCS

6. BUT EVERYONE
WANTS GOOD API DOCS

7. REMEMBER WHEN WE
CHALLENGED THE VALUE
OF WRITING TESTS?
AND HOW MUCH TIME IT TAKES?

8. THE FIRST TIME
I ASKED A CTO
TO TAKE TIME
FOR TESTS ✋

10. TODAY, WE HAVE SOME
DECENT TOOLS FOR
TESTING

11. FOR APIS, THE STORY IS
A BIT DIFFERENT

12. PUBLIC APIS DOCS ARE
A MARKETING TOOL

13. AND MARKETING IS
RICH💰

14. MARKETING PEOPLE
INVEST ON IT WITH
TECHNICAL WRITERS,
GREATS DESIGNS AND
CUSTOM TOOLS

15. PRIVATE APIS DOCS
AREN’T A MARKETING
TOOL, BUT A DEV TOOL.

16. WHO
CARES?

17. SOME HAVE TRIED

18. BLUEPRINT, RAML, PRS,
WIKIS, SLACK DMS, AT
THE COFFEE MACHINE…
OR SOMETIMES NEVER !

20. IT’S A GROWING
PROBLEM 😬

21. INSTEAD OF HAVING
ONLY 1 API TO DEAL
WITH, WE INVENTED
MICRO SERVICES™ 😎

22. WE ARE
DOOMED

23. WHY THEY’VE FAILED?

24. IT’S NOT
ONLY ABOUT DOCS

25. IT’S ABOUT
DOCS

26. IT’S ABOUT
UPFRONT DESIGN

27. IT’S ABOUT
CHANGES
COMMUNICATION AND
ANNOUNCEMENTS

28. IT’S ABOUT
CHANGES CONTINUOUS
TEST AND VALIDATION

29. IT’S ABOUT
API CLIENTS NOT
LAGGING BEHIND

30. IT’S ABOUT A WHOLE
ECOSYSTEM OF TOOLS
AROUND THE API

31. API SPECIFICATIONS
FTW✌

32. TONY TAM INVENTED
SWAGGER A LOOOOONG
TIME AGO*
*2011

33. NOW KNOWN AS
OPENAPI
https://spec.openapis.org/oas/v3.0.2

40. I STILL HAVE TO WRITE
IT 😩

41. I CAN DO SO MUCH
WITH IT 🥳

42. TOOLS!

43. EDITORS
Vim, VSCode, Atom, <your favorite one> extensions for
validation, linting, intellisense, …

44. OPENAPI-GUI

45. SPOTLIGHT STUDIO ❤

46. SWAGGER EDITOR

47. LINTERS
Speccy, github.com/wework/speccy
Spectral, github.com/stoplightio/spectral

48. DOCS
Swagger UI
Widdershins + Slate or Shins.js
Bump, bump.sh
ReDoc

50. MOCK SERVERS
Mock HTTP server and respond realistically
Server validation
Validation proxy
🔜 Recording / "Learning" mode to create spec files
🔜 Data Persistence (aka sandbox mode)

51. MOCK SERVERS
Prism, github.com/stoplightio/prism
APISprout, github.com/danielgtaylor/apisprout

52. TESTING
Postman
OpenAPI 🔄 JSON Schema conversion

55. CLIENTS GENERATION
OpenAPI Generator

56. 🎁 OPENAPI.TOOLS
120+ curated tools thanks to
Phil Sturgeon and Matthew Trask

57. WHAT ABOUT NON
RESTFUL APIS?

58. FRAN MENDEZ TO THE
RESCUE WITH
ASYNCAPI*
*2016

59. BASED ON OPENAPI
IDEAS,
BUT FOR EVENT-BASED
APIS

64. TOOLS!

65. ASYNCAPI.COM/DOCS/
TOOLING/

66. VALIDATION
You’d like to validate in real-time your Kafka messages?
asyncapi.stream got you covered!

68. THAT’S NICE,
NOW HOW TO MAKE IT
EVEN NICER?

69. SPECIFICATIONS AS
CONTRACTS🤝

70. A SPEC FIRST
WORKFLOW

71. 1. DISCUSS THE DESIGN

72. 2. WRITE THE SPEC

73. 3. GENERATE DOCS AND
MOCK API

74. 4. REFINE THE SPEC

75. 5. USE IT IN TESTS

76. 6. WRITE THE ACTUAL
CODE 😬

78. 7. PUSH THE CODE

79. 8. CI RUNS

80. 8. CI RUNS
VALIDATE THE SPEC,

81. 8. CI RUNS
VALIDATE THE SPEC, UPDATE
DOCS,

82. 8. CI RUNS
VALIDATE THE SPEC, UPDATE
DOCS, UPDATE CLIENTS

83. 8. CI RUNS
VALIDATE THE SPEC, UPDATE
DOCS, UPDATE CLIENTS AND
NOTIFY ABOUT THE CHANGES

86. 💯 BENEFITS

87. SINGLE SOURCE OF
TRUTH

88. DOCUMENTATION AND
TESTS ALWAYS UP TO
DATE

89. BETTER WORKFLOWS
BETWEEN THE BACKEND
AND THE CLIENTS

90. BACKEND IS AGAIN THE
FRONTEND FRIEND 🤗

91. THANKS 😗