Swagger2 - Swagger RESTful API Documentation
0.28
THIS MODULE IS EXPERIMENTAL! ANY CHANGES CAN HAPPEN!
Swagger2 is a module for generating, parsing and transforming swagger API documentation. It has support for reading swagger specification in JSON notation and it can also read YAML files, if a "YAML parser" is installed.
This distribution comes with a Mojolicious plugin, Mojolicious::Plugin::Swagger2, which can set up routes and perform input and output validation.
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("file:///path/to/api-spec.yaml"); # Access the raw specification values print $swagger->tree->get("/swagger"); # Returns the specification as a POD document print $swagger->pod->to_string;
$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/.
$pointer = $self->specification; $self = $self->specification(Mojo::JSON::Pointer->new({}));
Holds a Mojo::JSON::Pointer object containing the Swagger 2.0 schema.
$pointer = $self->tree; $self = $self->tree(Mojo::JSON::Pointer->new({}));
Holds a Mojo::JSON::Pointer object containing your API specification.
$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.
Swagger2
$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 filename, URL path or "Content-Type" header reported by a web server.
$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 this object against the "specification", and return a list with all the errors found. See also "validate" in Swagger2::SchemaValidator.
Copyright (C) 2014, 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.