Document your APIs
in a way that we can actually trust
Do you trust that Engineers will…
-
Find that related wiki page?
-
Read that related wiki page?
-
Maintain that related wiki page?!
1. OpenAPI Specification
-
YAML or JSON
-
Documents all facets of your API
-
URLs & REST verbs
-
Parameters
-
Return values/errors
-
Models/DTOs
-
In-line Examples
-
Achievement: Create Full MedClaims spec file [IDE_DEMO]
2. Gradle plugin
-
Generate spec files from existing projects
-
Achievement: Full Records service spec
3. SwaggerUI
-
Browser UI for OAS spec files
-
Achievement: Browse Reports Microservice API[BROWSER DEMO]
4. Swagger Codegen
-
Generate client/server stubs from OAS spec
-
JAXRS, Jersey, RESTEasy, Spring
-
Typescript/Angular
-
Kotlin
-
No struts support :(
-
Achievement: Generate MedClaims API that matches live implementation
with all relevant Servers/Clients[IDE DEMO]
5. SwaggerHub
-
Ties all of these projects together
-
Source of truth for API documentation
-
Achievement: Browse MedClaims & Reports from the same hub[BROWSER DEMO]
The Dream
-
Each service generates/publishes OAS specs to SwaggerHub
-
Front-end & Back-end engineers start and continue with API spec
-
We only write/edit logic code.