view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/Fondation/OpenAPI.pm  view on Meta::CPAN

in the OpenAPI plugin config because the plugin that owns the table
knows best whether it should be exposed. This follows the Fondation
principle of self-contained bricks — the OpenAPI plugin only reads
what other plugins declare.

=head1 DEPENDENCIES

This plugin requires L<Fondation::Model::DBIx::Async>.

Transitively, it depends on L<Mojolicious::Plugin::OpenAPI> E<gt>= 5.12,
which requires L<JSON::Validator> E<gt>= 5.17.

=head2 Perl 5.40 Incompatibility

On Perl E<gt>= 5.40, L<Net::IDN::Encode> (a dependency of JSON::Validator
5.17+) fails to compile because its XS code calls C<uvuni_to_utf8_flags>,
removed from the Perl C API in 5.40. This cascades:

  Net::IDN::Encode → compile FAIL (Perl ≥ 5.40)
    → JSON::Validator 5.17+ → blocked by cpanm
      → Mojolicious::Plugin::OpenAPI 5.12 → blocked

B<Workaround on Debian:> the C<libnet-idn-encode-perl> package provides
a pre-compiled version that works on Perl 5.40:

  apt install libnet-idn-encode-perl

=head1 COMMANDS

=head2 openapi generate

Generates C<share/openapi.json> and C<public/js/validators.js> from
DBIx::Class sources discovered via the configured backend.

Options: C<-y> (overwrite without prompt), C<--output> (custom path).

=head1 RUNTIME

On startup (C<fondation_finalyze>), if C<share/openapi.json> exists it
is loaded via L<Mojolicious::Plugin::OpenAPI> for request validation.
C<x-auth> permissions and groups are translated into route-level
C<requires('fondation.perm')> and C<requires('fondation.group')>
conditions via the C<openapi_routes_added> hook, unifying protection
with HTML routes.
Swagger UI routes (C</swagger> and C</openapi.json>) are added in
development mode. If the spec is missing, a warning is logged and
startup continues.

=head1 OUTPUT FILES

=over

=item C<share/openapi.json>

OpenAPI 3.0.3 specification with API Base schemas, contextual
projections (only when different), and CRUD paths. Committed to the
application repository.

=item C<public/js/validators.js>

Client-side form validation via C<FondationValidators.validate()>.
Consumed by L<Fondation::Asset> bundles. Committed to the application
repository.

=back

Always run C<openapi generate> before C<asset generate>.

=head1 SEE ALSO

L<Mojolicious::Plugin::Fondation::OpenAPI::Command::openapi>,
L<Fondation::Model::DBIx::Async>,
L<Mojolicious::Plugin::OpenAPI>

=head1 AUTHOR

Daniel Brosseau <dab@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Daniel Brosseau.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut