Swagger2 - Swagger RESTful API Documentation
0.89
The Swagger2 distribution is no longer actively maintained. Only severe bug fixes and pull requests will move this code forward. The reason behind this is that the code is too complex and hard to maintain.
So what should you use instead?
Swagger2
Swagger2 is either not very useful or replaced by JSON::Validator.
Swagger2::Client
No alternatives. The issue with this module is that it does not understand if you have parameters with the same name. There might be a OpenAPI::Client at some point, but it is currently no plans to write it.
Swagger2::Editor
No alternatives.
Swagger2::POD
Swagger2::POD is not very good and also very hard to maintain. Mojolicious::Plugin::OpenAPI has a HTML renderer which makes documentation that is much easier to read and always in sync with the application.
When that is said: The renderer in Mojolicious::Plugin::OpenAPI need refinement.
Swagger2::SchemaValidator
Mojolicious::Plugin::OpenAPI has the validator built in. For other purposes, use JSON::Validator or JSON::Validator::OpenAPI instead.
Mojolicious::Command::swagger2
Mojolicious::Plugin::Swagger2
Use Mojolicious::Plugin::OpenAPI instead. Mojolicious::Plugin::OpenAPI plays much nicer together with the Mojolicious framework.
Swagger2 is a module for generating, parsing and transforming swagger API specification. It has support for reading swagger specification in JSON notation and as well YAML format.
Please read http://thorsen.pm/perl/programming/2015/07/05/mojolicious-swagger2.html for an introduction to Swagger and reasons for why you would to use it.
This distribution comes with a Mojolicious plugin, Mojolicious::Plugin::Swagger2, which can set up routes and perform input and output validation.
Swagger2 also comes with a Swagger2::Client generator, which converts the client spec to perl code in memory.
YAML parser
A YAML parser is required if you want to read/write spec written in the YAML format. Supported modules are YAML::XS, YAML::Syck, YAML and YAML::Tiny.
use Swagger2; my $swagger = Swagger2->new("/path/to/api-spec.yaml"); # Access the raw specification values print $swagger->api_spec->get("/swagger"); # Returns the specification as a POD document print $swagger->pod->to_string;
$pointer = $self->api_spec; $self = $self->api_spec(Mojo::JSON::Pointer->new({}));
Holds a Mojo::JSON::Pointer object containing your API specification.
$mojo_url = $self->base_url;
Mojo::URL object that holds the location to the API endpoint. Note: This might also just be a dummy URL to http://example.com/.
$ua = $self->ua; $self = $self->ua(Mojo::UserAgent->new);
A Mojo::UserAgent used to fetch remote documentation.
$mojo_url = $self->url;
Mojo::URL object that holds the location to the documentation file. This can be both a location on disk or an URL to a server. A remote resource will be fetched using Mojo::UserAgent.
$swagger = $self->expand;
This method returns a new Swagger2 object, where all the references are resolved.
$operations = $self->find_operations(\%q);
Used to find a list of Operation Objects from the specification. %q can be:
%q
$all = $self->find_operations; $operations = $self->find_operations($operationId); $operations = $self->find_operations({operationId => "listPets"}); $operations = $self->find_operations({method => "post", path => "/pets"}); $operations = $self->find_operations({tag => "pets"});
$file = $self->javascript_client;
Returns a Mojo::Asset::File object which points to a file containing a custom JavaScript file which can communicate with Mojolicious::Plugin::Swagger2.
See https://github.com/jhthorsen/swagger2/blob/master/lib/Swagger2/swagger2-client.js for source code.
swagger2-client.js is currently EXPERIMENTAL!
swagger2-client.js
$self = $self->load; $self = $self->load($url);
Used to load the content from $url or "url". This method will try to guess the content type (JSON or YAML) by looking at the content of the $url.
$url
$self = Swagger2->new($url); $self = Swagger2->new(%attributes); $self = Swagger2->new(\%attributes);
Object constructor.
$self = $self->parse($text);
Used to parse $text instead of loading data from "url".
$text
The type of input text can be either JSON or YAML. It will default to YAML, but parse the text as JSON if it starts with "{".
$pod_object = $self->pod;
Returns a Swagger2::POD object.
$json = $self->to_string; $json = $self->to_string("json"); $yaml = $self->to_string("yaml");
This method can transform this object into Swagger spec.
@errors = $self->validate;
Will validate "api_spec" against Swagger RESTful API Documentation Specification, and return a list with all the errors found. See also "validate" in JSON::Validator.
Copyright (C) 2014-2015, Jan Henning Thorsen
This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
To install Swagger2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Swagger2
CPAN shell
perl -MCPAN -e shell install Swagger2
For more information on module installation, please visit the detailed CPAN module installation guide.