Skip to content

chore: Add OpenAPI 3 document#36

Open
duncanbeevers wants to merge 2 commits intoheatsynclabs:developfrom
sparkstudiosalem:feat/openapi-3
Open

chore: Add OpenAPI 3 document#36
duncanbeevers wants to merge 2 commits intoheatsynclabs:developfrom
sparkstudiosalem:feat/openapi-3

Conversation

@duncanbeevers
Copy link
Contributor

@duncanbeevers duncanbeevers commented May 18, 2023

✏️ Changes

  1. Add a plugin to generate an OpenAPI v3 document from the HAPI definitions
  2. Remove the verify_password field from the password reset API

🌻 Plugins & OpenAPI versions

The hapi-swagger plugin has no plans to support OpenAPI v3
The hapi-openapi3 plugin doesn't generate interactive Swagger documenation

By supporting both, it should be possible to use both schema types simultaneously.
Client-side tooling has mostly consolidated around v3, so I want this schema exposed in order to make writing the client simpler.

🪚 Simplifying the API

The members_api app is designed code-first, and the OpenAPI spec is extracted from the implementation.

The implementation used the joi library to request the verify_password field in the password reset API request, and to validate that the two fields have the same value.

This fancy validation is not directly expressible in OpenAPI, and led to a weird error when trying to generate TypeScript types and fetch clients for the API.
Furthermore, it's kind of a silly demand of the API.

So I removed the verify_password field from the API entirely.

🔧 Steps to test

  1. Start API
  2. Visit documentation http://127.0.0.1:3004/documentation
  3. Visit OpenAPI v2 schema http://127.0.0.1:3004/swagger.json
  4. Visit OpenAPI v3 schema http://127.0.0.1:3004/openapi.json

Remove password verification field from password reset API
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant