API Contract as Code: Rapid Development with OpenAPI
0 likes499 views
The document discusses keeping API documentation synchronized with implementation using OpenAPI specifications. It presents the benefits of defining APIs through "contract-as-code", including improved communication through documentation and leveraging code generation. The document outlines a workflow for developing APIs using OpenAPI specifications, including validating that implementations match the specifications. It also notes new features in OpenAPI 3.0 that provide additional descriptive capabilities.
API Contract as Code: Rapid Development with OpenAPI
- 1. TED EPSTEIN, FOUNDER & CEO | Ted.Epstein@RepreZen.com 1COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. API Contract as Code Rapid Development with OpenAPI
- 2. First Swagger Value Proposition • Keep your API docs in sync with implementation! … and look cool doing it! COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 2
- 3. Code-First • Or “API Code-as-Contract” COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 3
- 4. So why not all code, all the time? • Not Cross-functional team-friendly ◦ Coders aren’t always the best communicators. ◦ Tech writers don’t want to maintain embedded code comments (and you may not want them to). • De-emphasizes API design ◦ Outside-in design, from the user’s perspective ◦ As a distinct process ◦ Leveraging available tools for docs, mocking, testing, etc. ◦ Conscious, collaborative focus to API design quality COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 4
- 5. But there’s another reason… • Leverage ◦ Higher productivity ◦ Greater expressive power • An OpenAPI Description is code! ◦ High focus, high abstraction ◦ Generated code can be a scaffold to get started quickly… ◦ … and it can be first-class code. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 5
- 6. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 6 API Contract-As-Code Development Workflow
- 7. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 7 API Contract-As-Code Development Workflow
- 8. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 8 API Contract-As-Code Development Workflow
- 9. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 9 API Contract-As-Code Development Workflow
- 10. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 10 API Contract-As-Code Development Workflow
- 11. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 11 API Contract-As-Code Development Workflow
- 12. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 12 API Contract-As-Code Development Workflow
- 13. Demo COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 13
- 14. Achieving Separation • “Write-once” codegen for implementation • Delegation • Interface / Implementation • Abstract Base Class / Concrete Implementation • Dependency Injection • Dynamic merge (e.g. C# partial classes) COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 14
- 15. Project Layout • All in one project • One project for API spec, generate into second project for implementation • Generated library COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 15
- 16. Validating Implementation vs. Spec Implementation Completeness: “Every method is implemented” ◦ Use static typing when available ◦ Use generated or dynamic unit tests for dynamic languages Specification Completeness “Every method implemented is in the specification” ◦ Harder to enforce, but easy to prevent. ◦ Static code analysis or reflective tests could be useful Correctness Methods implement the contract (mechanics) Methods have the expected outcome (semantics) ◦ Use testing tools or frameworks, same as as you would with code-first COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 16
- 17. OpenAPI 3.0 - More Descriptive Power, New Possibilities…- • Links • Callbacks • oneOf / anyOf Schemas • Component Model COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 17