Download as PDF, PPTX
Uploaded byGOG.com dev team
Always up to date, testable and maintainable documentation with OpenAPI
The document discusses the challenges of maintaining accurate and complete API documentation, highlighting issues such as incompleteness and inconsistency that can hinder integration and increase costs. It emphasizes the importance of using API specification standards like OpenAPI to automate documentation processes and ensure that they are always up to date. Finally, it outlines a workflow for seamless documentation updates and testing implementation against specifications to improve API usability and reduce frustration.
More Related Content
Similar to Always up to date, testable and maintainable documentation with OpenAPI
Always up to date, testable and maintainable documentation with OpenAPI
- 1. Always up todate, testable and maintainable documentation with OpenAPI 1 Mieszko Malawski Software Engineer at GWENT LiveOps [email protected]
- 2. 2 Have you everhad to integrate with an API … … that had missing, incomplete or misleading documentation? Was it easy? Was it fun?
- 3. 3 Have you everhad to develop an API? Was your documentation always up to date? Was it always complete and 100% accurate? Do you love writing documentation?
- 4. ORDER OF BUSINESS 4 1.Issues with documentation 2. Why should You care? 3. Why issues with documentation exist 4. API specification standards 5. OpenAPI 6. Generating documentation 7. Testing implementation against spec (contact testing) 8. GOG Gwent workflow
- 5. ISSUES WITH DOCUMENTATION 5 •No documentation • Incomplete documentation (hidden endpoints, hidden fields) • Inconsistent docs - implementation works differently than described • Poorly described • No examples
- 6. WHY SHOULD YOUCARE? 6 For public APIs: • Integration is difficult and time consuming. Potential client (and their clients) may choose competition because of that • Your company loses potential revenue • Bad PR • More tickets to support dept. (how do I do X via API… ) - more time lost, time == money
- 7. WHY SHOULD YOUCARE? 7 For internal APIs: • Increases time of integration between teams. Client team has to extract “hidden knowledge” from providers and work by trial and error • Time loss. Time == Money • More bugs due to improper usage of API • Frustration
- 8. WHY ISSUES WITHDOCUMENTATION EXIST? 8 • Devs forget to do it • No time for it (we will update it later) • Nobody likes writing documentation • No way of checking if docs are in line with implementation • Usually not part of code review (docs in separate repo/web page) • Business sees no value in it
- 9. EXAMPLE: HOW ITLOOKED IN GWENT TEAM 9 1. Documentation written by hand using internal loosely defined “standard” 2. Written on internally accessible web page 3. Flow • Make change • Submit MR • Merge • Update documentation page - If You remember and have time for it
- 10. EXAMPLE: HOW ITLOOKED IN GWENT TEAM 10 • Incomplete docs: missing endpoints, fields, possible responses • Outdated docs • Incorrect docs • Request and response body described but usually little info about headers and authorisation • Lots of time spent on writing it • No examples
- 11. WE CAN DOBETTER 11 • Have reliable process of creating and maintaining documentation • Automate this process as much as possible • Have one way of describing APIs • Test automatically that documentation tells truth
- 12. API SPECIFICATION STANDARDS 12 •Spec readable both for humans and machines • Written by humans • Read by machines • Generate documentation from spec • Test implementation against spec • Generate mocks, client and servers
- 13. API SPECIFICATION STANDARDS 13 •Swagger/OpenAPI • Only REST APIs • Uses yaml/json format for spec (but is not limited to describing json payloads!) • Raml • Not limited to REST • Uses Yaml • API Blueprint • Uses Markdown
- 14. FIRST ATTEMPT: APIBLUEPRINT 14 https://apiblueprint.org/
- 15. FIRST ATTEMPT: APIBLUEPRINT 15 Our initial choice: • Apiary Online editor with schema validation, ACL, templates • Very descriptive Issues: • Too verbose • Markdown not so friendly for describing APIs
- 16.
- 17.
- 18. LET’S TRY OPENAPI 18 •Well adopted • Lots of good tools • Well documented • Schema re-usability • Tools support for PHP • Can use references
- 19. OPENAPI: MAJOR FEATURES 19 Basicinformation about your API
- 20.
- 21.
- 22.
- 23.
- 24. DOWNSIDES OF OPENAPI 24 •Learning curve. Not hard but requires some time to learn to write proper schemas. GUI editors and IDE plugins can help here • Only HTTP • Only REST (RESTish) • No clear way of describing versioning of API • No ACL
- 25. OPENAPI AND SWAGGER- CLARIFICATION 25 OpenAPI - https://www.openapis.org/about vendor free API description format Swagger - tools based on OpenAPI spec (generators, validators, editors) • https://openapi.tools/ • https://swagger.io • https://github.com/OAI/OpenAPI-Specification/blob/master/ IMPLEMENTATIONS.md • http://openapi.toolbox.apievangelist.com Originally swagger was name of the spec (made by SmartBear company).
- 26. SPEC FIRST VSCODE FIRST 26 Code first: • Write code first • Generate spec from code: • Symfony Nelmio bundle https://symfony.com/doc/master/bundles/ NelmioApiDocBundle/index.html • API Platform https://api-platform.com/ • Laravel https://github.com/DarkaOnLine/L5-Swagger
- 27. SPEC FIRST VSCODE FIRST 27 Spec first: • Write spec - allows You to discuss and modify Your API design before writing any code! • (Optional) Generate mocks and play with them • Once agreed on spec, write code (can be partly generated from spec) • Test your code against spec • Since spec is written first, there is no way that there can be missing documentation
- 28. HOW TO GETSTARTED? 28 1. Read openapi spec, get familiar with examples: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/ 3.0.2.md 2. Write Your first spec! For PHPStorm users there is this plugin: https://plugins.jetbrains.com/plugin/8347-swagger 3. Or use GUI to create spec and export it: Apicurio studio: https://studio.apicur.io Swagger hub https://app.swaggerhub.com 4. Or use online editor like https://editor.swagger.io/ 5. Check correctness of your spec with speccy https://github.com/wework/speccy
- 29.
- 30.
- 31.
- 32.
- 33. TESTING IMPLEMENTATION AGAINSSPEC 33 Dredd https://dredd.org/en/latest/ • Experimental support for OpenAPI v3 • Written in node.js (but can test any implementation - PHP also) • Reads spec. Creates requests based on operations, makes requests and then expects that responses matches given example • Allows to setup fixtures via language specific hooks
- 34. TESTING IMPLEMENTATION AGAINSTSPEC 34 OpenAPI validator https://gitlab.com/mmalawski/openapi-validator • Written in PHP • Disclaimer: I wrote it • Validates response data against OpenAPI schema • Uses json-guard under the hood
- 35.
- 36.
- 37.
- 38.
- 39.
- 40.
- 41.
- 42.
- 43.
- 44. RESULT 44 • When merged- documentation is automatically updated and available • Documentation always up to date • Implementation is tested against spec • Spec is part of code review - more issues were spotted and removed before writing code • Spec is under version control - we can see how it evolved • No time spent on documentation maintenance
- 45. THINGS TO IMPROVE 45 •New features are documented but some older endpoints are still in confluence. We are slowly covering these. • Validation not fully adopted • Generate parts of code responsible for serialisation and validation - currently all code is written by hand
- 46.
- 47.