Swagger bridge for veneer endpoint documentation
PHP
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.md
swagger-v1.php

README.md

""

What does it do?

veneer-swagger is an extension to the veneer framework that will massage the usual endpoint definitions into usable swagger documentation format. This means you can have web documentation, developer experimentation tooling, and example client code generation, without writing any extra code!

What is Swagger?

Swagger, per its project page at http://swagger.worldnik.com, is:

a specification and complete framework implementation for describing, producing,
consuming, and visualizing RESTful web services.

What you need to know is that it's a super-slick collection of HTML, CSS, and Javascript that creates an explorable REST API experience without much effort.

How do I use veneer-swagger?

A minimal implementation involves:

  • Downloading swagger-v1.php
  • Including swagger-v1.php in your code, as you would any other API endpoint
  • Installing swagger-ui on a webserver
  • Pointing swagger-ui at [your-api-url-here]/v1/swagger

If your API is publicly accessible, you could even "try before you buy" by visiting the online demo, changing the URL field to point to [your-api-url-here]/v1/swagger, and pressing the "Explore" button. Instant documentation!

Caveats

Since Swagger is run entirely in your browser, it is susceptible to the same origin policy. To work around this (and there are many ways), a few things you might do could include:

  • If you are using Apache, add a header to every request within an Apache directory tag: Header set Access-Control-Allow-Origin "*"
  • Within your endpoint code, set an access control header: $this->response->set_header('Access-Control-Allow-Origin: *');
  • Run swagger and your API code within the same domain