Discussion: proposed breaking changes in version 3.0

[striglia]

I wanted to make this tracking ticket for what deprecated features we can remove (!) in version 3.0.

Known things to remove:

• Remove all support for Swagger version 1.2
• Deprecated configuration flag skip_validation #63
• From #156 discussion - remove pyramid_swagger.schema_directory in favor of pyramid_swagger.schema_file only.

Feel free to write additional ideas or concerns with these in comments below.

[ergo]

I think by default schema file should be loaded not from file directory but from package resource.

schema_dir = pkg_resources.resource_filename('yourapp', 'api_docs')

I think the schema definition is something that is strongly tied to application.

[ergo]

Next thing, it seems that default mode of operation is to blacklist some resources from being validated by swagger with pyramid_swagger.exclude_paths.

Wouldn't it make more sense to rework that to pyramid_swagger.include_paths, so instead of doing something like: '^\/(?!api).*' I could just whitelist everything starting with /api?.

[ergo]

@striglia Also, I worked around this in my application code, but I think a default way of loading swagger definition from python package definition would be great.

schema_dir = pkg_resources.resource_filename('p2s_ml_webservice', 'api_docs')
settings['pyramid_swagger.schema_directory'] = schema_dir

This is what I'm doing doing right now to avoid absolute paths, I would expect that when application is distributed the schema files are distributes with it so setting paths could be avoided.

[striglia]

@ergo can you open up a separate issue on the subject of resource file paths? I think I'd find an example useful as I'm not entirely sure what you mean by "schema definition is strongly tied to application" and how that conflicts with the current implementation.

Thanks!