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.

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