Skip to content

Latest commit

 

History

History
190 lines (125 loc) · 3.58 KB

PITCHME.md

File metadata and controls

190 lines (125 loc) · 3.58 KB
Raw

---?image=presentation/title.png&size=contain%&position=left

@snap[east headline text-white span-70] Approaches to REST API documentation @snapend

@snap[south-east byline text-white] Mathias Düsterhöft @snapend

---?color=#00A551

For public APIs there is no way around an API reference

---?color=#0073BF

API reference and application code need to be in sync

Example code

The different approaches are shown in the contexts of a spring boot 🍃 application.

@fa[github]mduesterhoeft/approaches-to-api-doc-talk

Considered approaches

  • introspection
  • test-driven
  • design first

---?color=#FFCD53

Introspection

Use code introspection to get information about the API

Introspection - SpringFox

Automated JSON API documentation for APIs built with Spring

  • SpringFox applies the usual Swagger approach
  • generates OpenAPI specification using code introspection

---?image=presentation/demo.jpeg

@fa[terminal] SpringFox Demo

@snap[north message-box]

Introspection

@snapend

@snap[north-west thumb]

👍

@snapend

@snap[north-east thumb]

👎

@snapend

@snap[west sw fragment] @ul

  • easy to apply
  • API reference UI ships with code @ulend @snapend

@snap[east sw fragment] @ul

  • intrusive
  • pollute code with @
  • model often is != API @ulend @snapend

---?color=#0073BF

Test-driven

Generate API reference from API integration tests

Test-driven - Spring REST Docs

Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test.

Spring REST Docs @fa[link] restdocs-openapi

---?image=presentation/demo.jpeg

@fa[terminal] Spring REST Docs Demo

@snap[north message-box]

Test-driven

@snapend

@snap[north-west thumb]

👍

@snapend

@snap[north-east thumb]

👎

@snapend

@snap[west sw fragment] @ul

  • good guarantees in terms of accurateness
  • combines assertions and documentation @ulend @snapend

@snap[east sw fragment] @ul

  • test code grows a lot @ulend @snapend

---?color=#00B369

Design First

@fa[pencil] Design your API first using an API specification.

@fa[recycle] Then verify that your API complies with the specification in your test code.

Design First

Support the actual work-flow

API design usually happens before starting to implement.

So why not starting with the API specification

Design First

Swagger Request Validator

A Java library for validating HTTP request/responses against an OpenAPI specification.

@fa[link] Swagger Request Validator

---?image=presentation/demo.jpeg

@fa[terminal] Swagger Request Validator Demo

@snap[north message-box]

Design first

@snapend

@snap[north-west thumb]

👍

@snapend

@snap[north-east thumb]

👎

@snapend

@snap[west sw fragment] @ul

  • supports the way teams (usually) work
  • good tooling support
  • easy tech-writer integration
  • low impact on code @ulend @snapend

@snap[east sw fragment] @ul

  • sync between design tool and repository
  • certainty limited by verification library @ulend @snapend

---?color=#FFCD53

Questions?