Skip to content

generate-api-classes.md

Latest commit

 

History

History
128 lines (78 loc) · 3.98 KB

generate-api-classes.md

File metadata and controls

128 lines (78 loc) · 3.98 KB
Raw

Generate API models and services from Swagger API docs

General idea

Apigility allows to easily create / update / delete API endpoints (eg. add new properties, modify models).

Thus they are changing a lot.

Doctrine Entities and PHP models are generated automatically by Apigility upon each change.

Angular frontend is a separate application in a different language (TypeScript), but also requires same same structure (models and services).
It's very hard to maintain both frontend and backend models manually, so the best option to generate them automatically (at least the basic structure).

API Docs

Apigility also generates API documentation (and keeps it updated).

The documentations are in:

Swagger is a complete, live API documentation which allows to interact with the API.

Apigility uses [Swagger UI](https://swagger.io/tools/swagger-ui/ v.2.1

The Swagger JSON format is in v.2

Generating the classes

ng-swagger-gen package allows to automatically generate classes required by Angular frontend (models, services) given JSON schema generated by Swagger UI

By default, Swagger UI serves the documentation in HTML format,
unless you add accept: application/vnd.swagger+json HTTP request header.

The process of the generation is simple:

  1. download JSON schema file from Swagger
  2. use ng-swagger-gen to convert it to required classes

Downloading JSON schema from Swagger API docs

  1. Go to your Swagger UI interface and navigate to API and version you want to export

This will be an URL similar to: http://localhost:8083/apigility/swagger/Testing-v1

At the top of this page you have the text input box, with the URL you need, eg:

http://localhost:8083/apigility/documentation/<api-name>-<version>
eg.
http://localhost:8083/apigility/documentation/Testing-1

note this URL, you will use it in the next script.

  1. Download the JSON file using CURL adding accept: application/vnd.swagger+json

For this you may use bin/swagger-api-json.sh script.

eg.

./bin/swagger-api-json.sh http://localhost:8083/apigility/documentation/Testing-v1
or
npm run download-api-schema http://localhost:8083/apigility/documentation/Testing-v1

The file will be saved in:

src/app/api/schema.json

Generating the models and services

Call:

npm rum generate-api-classes

This will generate (or update overwriting) the API models and services in the directory:

src/api/generated/

You need to fine tune them, move in the place you need them.

More information

ng-swagger-gen docs

Alternative options

We may also use swagger-angular-generator which generates more complex structure, including optional NGRX modules for endpoints.

(There were some errors during usage, so sticked to ng-swagger-gen))

Once the Swagger UI is updated to the latest version (which supports OpenApi since v.3) we can use another generator: ng-openapi-gen

Generate anything based on JSON schema

Since we have up to date API schema in JSON format (downloaded from Swagger UI), we may generate anything we need ourselves (eg. using PHP CLI).

Save JSON API schema via PHP (no CURL)

The JSON required by Swagger is generated in:

vendor/zfcampus/src \ZF\Apigility\Documentation\Swagger\ViewModel.php

To save it to file, simply add something like:

file_put_contents(__DIR__ . '/dump.json', trim(var_export(json_encode($model->toArray()), true), "'"));

to:

// zfcampus src \ZF\Apigility\Documentation\Swagger\ViewModel::getVariables()