Date post: | 22-Jan-2018 |
Category: |
Software |
Upload: | smartbear-software |
View: | 45 times |
Download: | 2 times |
TED EPSTEIN, FOUNDER & CEO | [email protected]
1COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED.
API Contract as CodeRapid Development with OpenAPI
First Swagger Value Proposition• Keep your API docs in sync with implementation!
… and look cooldoing it!
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 2
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
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
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 10
API Contract-As-CodeDevelopment Workflow
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 11
API Contract-As-CodeDevelopment Workflow
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 12
API Contract-As-CodeDevelopment Workflow
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
Project Layout• All in one project
• One project for API spec, generate intosecond project for implementation
• Generated library
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 15
Validating Implementation vs. SpecImplementation Completeness:“Every method is implemented”◦ Use static typing when available
◦ Use generated or dynamic unit tests fordynamic languages
Specification Completeness“Every method implemented is in the specification”◦ Harder to enforce, but easy to prevent.
◦ Static code analysis or reflective tests couldbe useful
CorrectnessMethods 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
OpenAPI 3.0 - More Descriptive Power, New Possibilities…-• Links
• Callbacks
• oneOf / anyOf Schemas
• Component Model
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 17