FireTail uses the operationId from each Operation Object to identify which Python function should handle each URL.
If you provided this path in your specification POST requests to http://MYHOST/hello_world, it would be handled by the function hello_world in myapp.api module.
Optionally, you can include x-swagger-router-controller in your operation definition, making operationId relative:
Note: If you are using an OpenAPI spec, you should use x-openapi-router-controller in your operation definition, making operationId relative:
If all your operations are relative, you can use the RelativeResolver class instead of repeating the same x-swagger-router-controller or x-openapi-router-controller in every operation:
Keep in mind that FireTail follows how HTTP methods work in Flask and therefore HEAD requests will be handled by the operationId specified under GET in the specification. If both methods are supported, firetail.request.method can be used to determine which request was made.
By default, FireTail strictly enforces the presence of a handler function for any path defined in your specification. Because of this, adding new paths without implementing a corresponding handler function will produce runtime errors and your application will not start. To allow new paths to be added to your specification, for example, in an API design first workflow, set the resolver_error to configure FireTail to provide an error response for paths that are not yet implemented:
To customize this behavior, FireTail can use alternative Resolvers—for example, RestyResolver. The RestyResolver will compose an operationId based on the path and HTTP method of the endpoints in your specification:
RestyResolver will give precedence to any operationId encountered in the specification. It will also respect x-swagger-router-controller and x-openapi-router-controller. You may import and extend firetail.resolver.Resolver to implement your own operationId (and function) resolution algorithm.
Note: When using multiple parameters in the path, they will be collected and all passed to the endpoint handlers.
MethodViewResolver is a customized Resolver based on RestyResolver to take advantage of MethodView structure of building Flask APIs. The MethodViewResolver will compose an operationId based on the path and HTTP method of the endpoints in your specification. The path will be based on the path you provide in the app.add_api and the path provided in the URL endpoint (specified in the swagger or openapi3).
And associated YAML:
The structure expects a Class to exist inside the directory api that conforms to the naming <<Classname with Capitalised name>>View. In the above yaml the necessary MethodView implementation is as follows:
and a __init__.py file to make the Class visible in the API directory.
MethodViewResolver will give precedence to any operationId encountered in the specification. It will also respect x-swagger-router-controller and x-openapi-router-controller. You may import and extend firetail.resolver.MethodViewResolver to implement your own operationId (and function) resolution algorithm.
The names of query and form parameters, as well as the name of the body parameter are sanitized by removing characters that are not allowed in Python symbols that is, all characters that are not letters, digits or the underscore are removed, and finally characters are removed from the front until a letter or an under-score is encountered. As an example:
Without this sanitation it would be impossible for example, to implement an OData API.
You can also convert CamelCase parameters to snake_case automatically using a pythonic_params option:
With this option enabled, FireTail firstly converts CamelCase names to snake_case. Secondly, it looks to see if the name matches a known built-in and if it does it appends an underscore to the name.
FireTail supports Flask’s int, float, and path route parameter variable converters. Specify a route parameter’s type as integer or number or its type as string and its format as path to use these converters. For example:
This will create an equivalent Flask route /greeting/<path:name>, allowing requests to include forward slashes in the name URL variable.
Setting a base path is useful for versioned APIs. An example of a base path would be the 1.0 in http://MYHOST/1.0/hello_world.
If you are using OpenAPI 3.x.x, you set your base URL path in the server's block of the specification. You can either specify a full URL or just a relative path.
If you are using OpenAPI 2.0, you can define a basePath on the top level of your OpenAPI 2.0 specification.
If you don’t want to include the base path in your specification, you can provide it when adding the API to your application:
Swagger UI is available at /ui/ by default.
You can choose another path through options:
FireTail makes the OpenAPI/Swagger specification in JSON format available from swagger.json in the base path of the API.
You can disable the Swagger JSON at the application level:
You can also disable it at the API level: