Let’s talk about Swagger

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?!

Example image5

5 Components

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.