Swagger to HTML (beta)

Usage

To generate html output from an open api specification you can use the swagger_to_html tag, eg:

1
2
3
4
5
---
title: Petstore Api Reference
---

{% swagger_to_html <swagger_path> %}

The location of swagger file (<swagger_path>) can be a local file path or a URL.

Examples

With a local path: 

1
{% swagger_to_html ./petstore.yaml %}

With a URL: 

1
{% swagger_to_html  https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore.json %}

Demo

Download Schema

Swagger Petstore

Version: 2.0.0
A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification

Security Definitions

oauth

The type of security scheme is oauth2.
The flow used by the OAuth2 security scheme is password.
The token URL to be used for this flow is https://auth.example.com/oauth2/token.
The available scopes for the OAuth2 security scheme are as follows.
petstore.read: Access to read petstore
petstore.write: Access to write to petstore

Get pets

Returns all pets from the system that the user has access to.
GET
/pets

Security Requirement

petstore.read scope is required for oauth.

Request

Sample Request

Header
Authorization
string (OAUTH2 (IAM) or JWT token)
required
OAUTH2 (IAM) or JWT token
Path
limit
integer (int32)
Used in query
Maximum number of results to return 
curl -v -X GET http://petstore.swagger.io/api/pets?limit=10  \
-H "Authorization: Bearer <Access-Token>"

Response

Sample Response

Status Code: 200
Pet response.
Reference
data
array
List of pets
data[]
object
Pet description
data[].id
integer
Id of pet
data[].name
string
Name of pet
Eg. Foo
data[].type
string
Type of pet
Eg. cat
data[].gender
enum
Gender of pet
Allowed values: male, female. 
{
  "data": [
    {
      "id": 1,
      "name": "Foo",
      "type": "cat",
      "gender": "female"
    },
    {
      "id": 2,
      "name": "Bar",
      "type": "dog",
      "gender": "male"
    }
  ]
}
Status Code: 403
Forbidden
Reference
code
integer (int32)
required
Status code
message
string
required
Status message
This is a default response for the request.
unexpected error
Reference
code
integer (int32)
required
message
string
required

Create a pet

Creates a new pet in the store. Duplicates are allowed
POST
/pets

Security Requirement

petstore.write and petstore.read scopes are required for oauth.

Request

Sample Request

Header
Authorization
string (OAUTH2 (IAM) or JWT token)
required
OAUTH2 (IAM) or JWT token
Request Body
name
string
required
Name of pet
Eg. Foo
type
string
Type of pet
Eg. cat
gender
enum
Gender of pet
Allowed values: male, female. 
curl -v -X POST http://petstore.swagger.io/api/pets  \
-H "Authorization: Bearer <Access-Token>"  \
{
  "name": "Foo",
  "type": "cat",
  "gender": "female"
}

Response

Sample Response

Status Code: 201
pet response
Reference
id
integer
Id of pet
name
string
Name of pet
Eg. Foo
type
string
Type of pet
Eg. cat
gender
enum
Gender of pet
Allowed values: male, female. 
{
  "id": 1,
  "name": "Foo",
  "type": "cat",
  "gender": "female"
}
Status Code: 403
Forbidden
Reference
code
integer (int32)
required
Status code
message
string
required
Status message
This is a default response for the request.
unexpected error
Reference
code
integer (int32)
required
message
string
required

Get a pet by id

Returns a user based on a single ID, if the user does not have access to the pet
GET
/pets/{id}

Security Requirement

petstore.read scope is required for oauth.

Request

Sample Request

Header
Authorization
string (OAUTH2 (IAM) or JWT token)
required
OAUTH2 (IAM) or JWT token
Path
id
integer (int64)
required
Used in path
ID of pet to fetch 
curl -v -X GET http://petstore.swagger.io/api/pets/1  \
-H "Authorization: Bearer <Access-Token>"

Response

Sample Response

Status Code: 200
pet response
Reference
id
integer
Id of pet
name
string
Name of pet
Eg. Foo
type
string
Type of pet
Eg. cat
gender
enum
Gender of pet
Allowed values: male, female. 
{
  "id": 1,
  "name": "Foo",
  "type": "cat",
  "gender": "female"
}
Status Code: 403
Forbidden
Reference
code
integer (int32)
required
Status code
message
string
required
Status message
This is a default response for the request.
unexpected error
Reference
code
integer (int32)
required
message
string
required

Delete a pet

Deletes a single pet based on the ID supplied
DELETE
/pets/{id}

Security Requirement

petstore.write and petstore.read scopes are required for oauth.

Request

Sample Request

Header
Authorization
string (OAUTH2 (IAM) or JWT token)
required
OAUTH2 (IAM) or JWT token
Path
id
integer (int64)
required
Used in path
ID of pet to delete 
curl -v -X DELETE http://petstore.swagger.io/api/pets/1  \
-H "Authorization: Bearer <Access-Token>"

Response

Sample Response

Status Code: 204
Pet deleted.
Reference
Status Code: 403
Forbidden
Reference
code
integer (int32)
required
Status code
message
string
required
Status message
This is a default response for the request.
unexpected error
Reference
code
integer (int32)
required
message
string
required