Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Add OpenAPI 3 document #36

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from

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