view release on metacpan or  search on metacpan

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

=encoding UTF-8

=head1 NAME

Mojolicious::Plugin::Fondation::OpenAPI - OpenAPI specification generator and runtime validator for Fondation applications

=head1 VERSION

version 0.05

=head1 SYNOPSIS

  # In myapp.conf
  'Fondation::OpenAPI' => {
      backend => 'main',
      schemas => {
          User => {
              columns => {
                  password => {
                      writeOnly => 1,
                      create    => { required => 1 },
                      update    => { required => 0 },
                  },
              },
          },
      },
  }

  # Optional: disable the client-side validators.js rules
  'Fondation::OpenAPI' => {
      no_validator_js => 1,
  }

  # CLI
  $ myapp.pl openapi generate
  $ myapp.pl openapi generate -y
  $ myapp.pl openapi generate --output custom.json

=head1 DESCRIPTION

This plugin provides the C<openapi generate> command to produce an
OpenAPI 3.0.3 specification from DBIx::Class sources. At runtime,
C<fondation_finalyze> loads the generated C<share/openapi.json> via
L<Mojolicious::Plugin::OpenAPI> for request validation and adds
Swagger UI routes in development mode.

=head1 CONFIGURATION

=head2 Plugin config

  'Fondation::OpenAPI' => {
      backend => 'main',          # optional -- falls back to DBIx::Async default
      schemas => { ... },         # optional -- column overrides
      no_validator_js => 0,       # optional -- default 0 (client validation on)
  }

=head3 C<no_validator_js>

When set to C<1>, C<openapi generate> still writes C<public/js/validators.js>
but the generated C<validate()> function accepts everything
(C<return { valid: true, errors: [] }>). Server-side OpenAPI validation is
unaffected. Use it to rely solely on server validation (e.g. during testing).

Re-enable client validation by setting it back to C<0> (or removing the key)
and regenerating. The same setting is exposed as a boolean parameter in the
plugin's C<fondation_meta> C<setup> block (default C<0>).

=head3 C<pattern> in column overrides

Column C<pattern> (like C<minLength>, C<maxLength>, C<format>...) is a flat
key accepted both in C<extra->{openapi}> (DBIx Result classes) and in the
C<schemas> config override. Patterns MUST be authored in ECMA-262 dialect:
the same regex is used by JSON::Validator server-side (Perl) and by
C<new RegExp()> in the generated validators.js. Avoid Perl-only constructs
(C<\z>, C<\A>, POSIX classes, variable lookbehind, ...).

=head2 Backend resolution

The backend name is resolved in this order:

=over

=item 1. OpenAPI's own C<backend> config

=item 2. DBIx::Async's C<default_backend> config key

=item 3. First backend in DBIx::Async's C<backends> array

=back

=head2 Schema config override

Any column property can be overridden via C<schemas> without modifying
DBIx Result classes. See L<Mojolicious::Plugin::Fondation::OpenAPI::Command::openapi>
for the full list of supported keys.

=head2 x-auth config override

Permission annotations on CRUD endpoints can be overridden via C<x_auth>
in the C<schemas> config. The default convention is
C<{moniker_lc}_{operation}> (e.g., C<user_create>, C<group_list>).

  'Fondation::OpenAPI' => {
      schemas => {
          User => {
              x_auth => {
                  create => {
                      permissions => ['admin_create_user'],
                      groups      => ['admins'],
                  },
                  list => {
                      permissions => [],   # public endpoint
                  },
              },
          },
      },
  }

Overrides replace the default entirely. An empty C<permissions> array
makes the endpoint public (no C<x-auth> in the generated spec).

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