view release on metacpan or  search on metacpan

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

  '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).
Additional constraint keys (C<groups>, C<features>, etc.) are translated
into C<requires()> route conditions at startup via the C<openapi_routes_added> hook.

=head2 openapi_exclude in plugin C<fondation_meta>

Plugins can declare tables that should be excluded from the generated
OpenAPI spec via C<openapi_exclude> in their C<fondation_meta>. This
is the canonical way to hide internal tables (pivot tables, audit logs,
etc.) that should never be exposed as public API endpoints.

  # In any Fondation plugin's fondation_meta:
  sub fondation_meta {
      return {
          defaults => {
              openapi_exclude => ['UserGroup'],
          },
      };
  }

Each entry is a DBIx::Class source moniker (class-derived name, e.g. C<UserGroup>),
matching the C<register_source> moniker used by Action::DBIx.
Excluded sources produce no CRUD
routes, no OpenAPI schemas, and no C<public/js/validators.js> entries.

B<Design:> The mechanism lives in plugin C<fondation_meta> rather than
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>