pyswagger

When converting from Swagger 1.2 to 2.0, be aware of the following structural changes and limitations:

Parameter Mapping: allowMultiple to collectionFormat

In Swagger 1.2, arrays were often defined using allowMultiple: true. In Swagger 2.0, this is replaced by the collectionFormat property. For example, a string with multiple allowed values will be converted to use collectionFormat: "csv" and an items object.

Example Conversion:

Input (1.2):

{
    "allowMultiple":true,
    "type":"string",
    "enum":[
        "available",
        "pending",
        "sold"
    ]
}

Output (2.0):

{
    "collectionFormat":"csv",
    "items":{
        "type":"string",
        "enum":["available", "pending", "sold"]
    }
}

basePath Restrictions

Swagger 1.2 allows multiple basePath definitions. However, Swagger 2.0 only allows a single basePath. If your resource files define different basePath values, pyswagger will raise an Exception and refuse to proceed with the conversion.

When dealing with multi-document specifications (such as Swagger 1.2 or Swagger 2.0 with $ref pointing to external files), you can use DictGetter by providing all resource paths and their corresponding loaded objects.

Important: You must pass all URLs/paths to be resolved in the correct order as the first parameter (a list) to DictGetter. The dictionary mapping must then match these paths to the loaded objects.

Note: This process is manual and requires careful ordering of the path list.

from pyswagger import App
from pyswagger.resolve import Resolver
from pyswagger.getter import DictGetter

# Example: multiple loaded objects in memory
loaded_resource_list = { ... }
pet = { ... }
user = { ... }
store = { ... }

# The order in the list must match the keys in the dictionary
getter = DictGetter([
    '',
    'pet.json',
    'user.json',
    'store.json',
], {
    '': loaded_resource_list,
    'pet.json': pet,
    'user.json': user,
    'store.json': store
})

app = App.load('', resolver=Resolver(default_getter=getter))
app.prepare()

You can retrieve an Operation object from an App instance using several methods depending on how your Swagger file is structured:

1. Via operationId or tag + operationId

If operationId is unique, you can access it directly via the app.op dictionary. If you need to disambiguate using a tag, provide a tuple of (tag, operationId).

2. Via JSON Pointer

Every object in a Swagger file can be referenced using a JSON Pointer. Use pyswagger.utils.jp_compose to build the pointer and app.resolve() to retrieve the object.

3. Via Cascade Resolving

You can resolve a path first (e.g., a specific resource) and then resolve the specific HTTP method (e.g., get, post) from that resource object. You can access methods as properties if they do not contain special characters.

from pyswagger import App, utils

app = App.create('http://petstore.swagger.io/v2/swagger.json')

# Using operationId
op = app.op['getUserByName']

# Using tag + operationId
op = app.op['user', 'getUserByName']

# Using JSON Pointer
op = app.resolve(utils.jp_compose(['#', 'paths', '/user/{username}', 'get']))

# Cascade resolving
username_api = app.resolve(utils.jp_compose(['#', 'paths', '/user/{username}']))
op = username_api.resolve('get') # Method 1
op = username_api.get            # Method 2 (property access)