API Contract as Code: Rapid Development with OpenAPI

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

https://swagger.io/

Code-First• Or “API Code-as-Contract”


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


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.


https://swagger.io/blog/api-first-approach-with-openapi-training/


API Contract-As-CodeDevelopment Workflow













Demo


Achieving Separation• “Write-once” codegen for implementation

• Delegation

• Interface / Implementation

• Abstract Base Class / Concrete Implementation

• Dependency Injection

• Dynamic merge (e.g. C# partial classes)


Project Layout• All in one project

• One project for API spec, generate intosecond project for implementation

• Generated library


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


OpenAPI 3.0 - More Descriptive Power, New Possibilities…-• Links

• Callbacks

• oneOf / anyOf Schemas

• Component Model


https://swagger.io/blog/difference-between-swagger-and-openapi/

API Contract as Code: Rapid Development with OpenAPI

Software