The YAML config file¶
The config file contains the entire definition for your application. The config file should be in YAML format. By default, Crudcast looks for a file called config.yml in the current folder on startup. For example:
$ ls -l -rw-r--r-- 1 chris.davies staff 229 Dec 10 08:42 config.yml $ crudcast * Serving Flask app "Crudcast" (lazy loading) * Environment: production WARNING: Do not use the development server in a production environment. Use a production WSGI server instead. * Debug mode: off * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
You can also specify a custom config file location
crudcast --config-file /path/to/config.yml
The full set of config options are documented below
Here is a very simple configuration that generates two different objects - person and address:
models: person: fields: first_name: last_name: required: true email_address: unique: true required: true age: type: number address: fields: house_number: type: number street_name: city: post_code: person: type: foreignkey to: person required: true
Each object has a fields attribute - this is an array of attributes to be applied to your object. In the case of the above objects, the person model has first_name, last_name, email_address and age fields. Note that:
- first_name has no options supplied, and therefore inherits the default field config - it is treated as a string field, which can be left blank.
- last_name also has no type specified, which means it too defaults to a string field. However, as we have set required: true, a validation error will get generated if we attempt to create or update a person object without providing this value
- email_address is another required text field. However, this field also adds the unique: true property - this means that on creating/updating a person, this field is validated to make sure that no other person objects with the same email_address already exist
- age specifies a different type - number. This means that the field will be validated to ensure that the input on creating/updating an object is numeric
The address object stores the simple text/numeric properties house_number, street_name, city, and post_code. However, this model also has a person field which uses the foreignkey field type. This field type allows you to create a relationship between one object and another. Note that when using the foreignkey field type, you must also provide a to value which corresponds to the name of another model. This allows our app to link person objects with address objects
There are a number of other different field types not listed here. For full details, refer to the fields page
Crudcast requires MongoDB, and the config file is used to tell Crudcast where to look for the MongoDB, and what to call the database. It can be set like as follows:
mongo_url: mongodb://localhost:27017/ db_name: database
The above example shows the default values. If you do not set these values, the above MongoDB configuration would still apply
To enable the user model, add users: to the top level of your config.yml:
This parameter does not currently support any additional options
You can require users to authenticate using basic auth to access the routes of a specific model by adding auth_type: basic to your model config
models: thing: fields: name: auth_type: basic
This will ensure that all users must be logged in to access the thing routes.
Setting an auth_type while not enabling the user model (see above) will cause your routes to be completely inaccessible
Documenting your API¶
Crudcast supports the OpenAPI specification, and automatically generates a Swagger view showing your fully documented API, and allowing you to test it. You can update the default Swagger documentation generated by Crudcast by adding a swagger: parameter to your config file.
swagger: swagger: 2.0 basePath: /api url: /api/docs info: description: This is an API automatically generated by crudcast version: 1.0.0 title: My Crudcast app
Note that you can also add a description value at a model level:
models: person: description: personal details <== fields: first_name: ...
The basePath is very important here - if you change this, all your routes will also change (not just in the documentation). Note that you must not include slashes in the middle of this value, e.g. /api/v1 is invalid
The url value refers to the location at which your swagger view is hosted