Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

API Contract-As-Code: Rapid Development with OpenAPI

185 views

Published on

Presented at SmartBear Connect 2017
Video: https://www.youtube.com/watch?v=MwdRWuTQZ3w

API-first puts the API at the center of your product strategy. Contract-first puts API design quality at the top of the agenda. But when it's time to start coding, can we really use an OpenAPI spec? Aside from telling us what to build, and maybe generating a one-time scaffold, what can it do for us? In this session, we'll leverage the expressive power of OpenAPI 3.0 in a fast, iterative development lifecycle. We'll show how, with a few basic rules in place, we can drive API evolution from the OAS contract, all the way through to microservice implementation.

Published in: Software
  • Be the first to comment

  • Be the first to like this

API Contract-As-Code: Rapid Development with OpenAPI

  1. 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. 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. 3. Code-First • Or “API Code-as-Contract” COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 3
  4. 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. 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. 6. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 6 API Contract-As-Code Development Workflow
  7. 7. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 7 API Contract-As-Code Development Workflow
  8. 8. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 8 API Contract-As-Code Development Workflow
  9. 9. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 9 API Contract-As-Code Development Workflow
  10. 10. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 10 API Contract-As-Code Development Workflow
  11. 11. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 11 API Contract-As-Code Development Workflow
  12. 12. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 12 API Contract-As-Code Development Workflow
  13. 13. Demo COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 13
  14. 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. 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. 16. Validating Implementation vs. Spec API Implementation Completeness: “Every specified method is implemented” ◦ Use static typing when available ◦ Use generated or dynamic unit tests for dynamic languages API Specification Completeness “Every implemented method is specified” ◦ 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. 17. OpenAPI 3.0 - More Descriptive Power, New Possibilities…- • Links • Callbacks • oneOf / anyOf Schemas • Component Model COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 17
  18. 18. Thank you! Prototype: https://github.com/RepreZen/ContractAsCode-SCGMaven (Improvements & code walkthrough coming soon.) COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 18

×