ezapi - generator

This generator creates an REST api endpoint for either a resource or actions of your choice. Additionally the generator provides integration specs for your actions, especially to be able to build an OpenAPI specification using rswag.

In short, if you use this generator you mostly do not have to do anything to get your api endpoint to work. The basics should work out of the box.

You can read details about the concepts for api endpoints using ez-on-rails here.

The generated actions return values in json format using jb views.

To generate a REST api endpoint for a resource you previously generated using ezscaff, execute the following command:

rails generate ez_on_rails:ezapi Article --resource Article --authenticable bearer

This command creates default REST actions to create, update, destroy, show, list and search records of your resource.

Your endpoints are protected using bearer authentication. You either can use bearer, oauth or no authentication. Note that if you do not pass any authentication method, your actions will be public. The permission to restrict the access to your endpoints will be written to the seeds. Hence you have to call rails db:seed after the generation to restrict the access. To understand how the permission system works you can have a look at the permission systems concept page. If you pass --authenticable with some value like bearer or api-key, the endpoints are restricted to members or users having valid api keys only, meaning that you have to be signed in or use a valid api key to access them. Feel free to change those permission in the seeds.

The controllers, views, and specs are located in the api namespace, hence you have to look in the api subfolder to locate them.

The generated integration specs are also used to create an OpenAPI specification. To accomplish this the needed json schemas are written to the swagger_helper located in the spec folder. The api generator calls the command to create the OpenAPI specification. If you changed something and you need to refresh the OpenAPI spec, you have to call rails rswag:specs:swaggerize. Consider reading the docs related to rswag to get comfortable with the concept of creating the specification using the integration specs. The resulting documentation is available at https://your-domain.de/api-docs.

Beside the integration specs, request specs are also generated. They are used to check the functionality and permissions.

To generate an endpoint that is not related to a resource execute the following command:

rails generate ez_on_rails:ezapi SystemStatus show report --authenticable bearer

This will create the two api barebone actions show and report in the system_status controller in the api namespace. This also creates some empty jb files and specs.

Options

If you only want to create barebones for customizable api actions you just have to pass the Name of your Endpoint as first parameter, followed by the names of the actions. Alternatively you can generate the full REST endpoint for a resource by passing:

• --resource ResourceName

In both cases you can restrict the access to your application by passing:

• --authenticable bearer
  • You can pass api-key instead of bearer to restrict the access to api keys
  • Alternatively you can pass oauth here

The following steps are executed by the generator

1. Generate the coontroller

• The controller in created in the app/controllers/api directory
• The name on the controller depends on the name you passed as first parameter to the generator

2. Generate json views

• The views are located in the app/views/api/ directory
• Every action (except for the destroy action in case of the resource enpoint) gets a jb file

3. Generate necessary swagger schemas, if not yet exists

• If the swagger_helper does not yet provide schemas ez-on-rails need, they are appended to the schemas section of this file
• Note that also security_schemas are appended here

4. Create specs

• The integration specs are located in _spec/integration/api/<your_endpoint_name>spec.rb
• The request secs are located in _spec/request/api/<your_endpoint_name>spec.rb

5. Generate routes

• The routes to access your endpoint are written to the config/routes.rb file

6. Add restrictions to seeds

• If you passed an authentication method, default restrictions giving only members access to the endpoint are written to the db/seeds.rb file

7. Generate OpenAPI specification

• The rswag generator to provide the OpenAPI specification will be called