adriengibrat / APItools.md

title: API 🛠 for 😄 & 🤖 author: name: I'm Adrien, I 🖤 API, a.k.a API lead 🤓 email: [e-mail] theme: ./theme controls: false output: index.html

--

API 🛠 for 😄 & 🤖

-- screen full

Tools?! 🤚 Thanks, but no thanks...

--

Why? 🧠

• Keep the API design process simple & enjoyable
• Get all the possible value from OpenAPI specs (OAS)
• Ensure rest API common practice and quality

-- screen

You need API specification anyway! 🤦‍♂️

we all did...

-- screen

API doc generated from code, don't need spec! 👊

Backend only write API doc 😅
API doc in code is awkward 🚨
Too much API code refactor 🤯

-- screen

API design first 🚀

1. You'll need a good editor
2. Be sure to write good spec
3. Deliver Mocks & Docs

--

OpenAPI editors ✍️

• Swagger editor quick & dirty online editor
• Openapi extension or
  Swagger plugin or
  KaiZen editor IDE integration
• Stoplight studio advanced specification suite

-- screen large

Stoplight studio 🎅

--

Start or migrate to OpenAPI 🏁

You can start from scrath or migrate to openAPI Specification!

[](https://www.apimatic.io/transformer/ "Transformer works great but automatic transform eventually require manual tuning") [Swagger, RAML, Blueprint & Postman to OpenAPI](https://www.apimatic.io/transformer/#supported-formats)

[](https://swagger-toolbox.firebaseapp.com/ "JSON or OpenAPI schema are verbose") [JSON sample to OpenAPI](https://swagger-toolbox.firebaseapp.com/)

--

Well written specification 👌

Ask and learn from the best ... no consumer yet!

Lint speccy spectral lint openapi.yml in &

Enforce common rules and standard practice

Detect changes openapi-diff & make changelog

-- screen

Tools already in CI 👷

Merge requests pipeline [

Tag pipeline

```yaml include: oogit.oodrive.net/ci-templates/api-doc/open-api-run.yml ```

--

Documentation 📑

• Swagger UI quick & easy documentation
• OpenAPI viewer clean & simple try out
• Redoc clear advanced documentation + Postman

-- screen large

Redoc: API docs you can be proud of 🤩

--

Redoc, pro tips 🤑

• Displays data types & formats
• Supports named examples
• Practical x-extension & plugins: tags, side-menu, code samples ...
• Futur version ^©️ may add try out, already a pro feature

Nah, really... just use Postman ;)

-- screen fullscreen

Postman, plug & play 📨

--

Mock 🌠

Fake auto-generated API allows you to

• Play with API from a simple spec file, even at the MR stage
• Start to implement client services & views upfront
• Collect feedbacks from customers / external partners

HTTP Mock server apisprout prism mock openapi.yml again

-- screen

Prism 🛆

--

Prism superpowers 🔋

• Validate request payload & params, send 400 otherwise
• Validate servers (request passthrough)
• Magic query params
  ?__example=myStuff&__code=404&__server=prod
• Generate realistic fake data using x-faker (vendor extention)

-- screen

POC with Portu, a CertEurope API 🔑

--

Next ? ⏭️

• Auto deploy Mock servers?
• Add internal API docs & tryout on API management Gravitee!
• Continue to support teams adopting design first with OpenAPI...
• Stay tuned with Louis Lin ;)