valgene_cli 1.0.5

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 48

Valgene CLI #

Build Status Coverage Status Pub

Introduction #

assuming you are providing some RESTful/Web APIs, then you are familiar with the tasks of

  • documenting the API
  • validating incoming data against the API specification
  • creating DTOs for dedicated API endpoints

Somehow these things are disconnected to each other, that means the documentation of the API is normally not used for validating incoming data. Neither it is used for writing a DTO class. As well all the tasks are repetitive, manual and error prone.

This is where Valgene kicks in and reduces a lot of pain.

Usage #

Valgene (Validation Generator) generates validator and DTO boiler plate code from your OpenAPI specs.

Given #

so lets assume you have an API spec like the following that defines 1 endpoint that accepts incoming data, that is [POST] /pets.

paths:
  /pets:
    post:
      description: Creates a new pet in the store.  Duplicates are allowed
      operationId: addPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'

The payload of the endpoint is expected to be like:

NewPet:
  required:
    - name  
  properties:
    name:
      type: string
    tag:
      type: string    

When #

when invoking valgene

valgene --template php5.5 --spec petstore-expanded.yaml --option 'php.namespace:\My\PetStore\Api'

Then #

it will generate a Validator, DTO and some Exception classes:

valgene --template php5.5 --spec petstore-expanded.yaml --option 'php.namespace:\My\PetStore\Api'
> processing petstore-expanded.yaml:
  - route [POST]    /pets
> generating:
  - PostAddPet/NewPetDto.php
  - PostAddPet/NewPetDtoValidator.php
  - Exception/MissingFieldException.php
  - Exception/FieldException.php
  - Exception/InvalidFieldException.php

Generated Validator looks like this:

<?php

namespace \My\PetStore\Api\PostAddPet;

use \My\PetStore\Api\Exception\InvalidFieldException;
use \My\PetStore\Api\Exception\MissingFieldException;

/**
 * GENERATED CODE - DO NOT MODIFY BY HAND
 */
class NewPetDtoValidator
{
    /**
     * @param array $json
     * @throws MissingFieldException
     * @throws InvalidFieldException
     */
    public function validate($json)
    {
        $this->isNameValid($json, true);
        $this->isTagValid($json, false);
    }

    /**
     * @param array $json
     * @param bool $isRequired
     */
    protected function isNameValid($json, $isRequired)
    {
        $field = NewPetDto::PROPERTY_NAME;
        if (!array_key_exists($field, $json)) {
            if ($isRequired) {
                throw new MissingFieldException($field, $json);
            }
        }
        $value = $json[$field];

        if (!is_string($value)) {
            throw new InvalidFieldException($field, $json, 'datatype is not string');
        }
    }

    /**
     * @param array $json
     * @param bool $isRequired
     */
    protected function isTagValid($json, $isRequired)
    {
        $field = NewPetDto::PROPERTY_TAG;
        if (!array_key_exists($field, $json)) {
            if ($isRequired) {
                throw new MissingFieldException($field, $json);
            }
        }
        $value = $json[$field];

        if (!is_string($value)) {
            throw new InvalidFieldException($field, $json, 'datatype is not string');
        }
    }
}

Generated DTO looks like this:

<?php

namespace \My\Sample\Api\PostPets;

/**
 * GENERATED CODE - DO NOT MODIFY BY HAND
 */
class NewPetDto
{
    const PROPERTY_NAME = 'name';
    const PROPERTY_TAG = 'tag';

    /** @var string $name */
    public $name;

    /** @var string $tag */
    public $tag;

    /**
     * @param array $payload
     * @return NewPetDto
     */
    public static function fromArray(array $payload)
    {
        $self = new static();
        $self->name = $payload[static::PROPERTY_NAME];
        $self->tag = $payload[static::PROPERTY_TAG];

        return $self;
    }
}

Customization of Templates #

Be aware that the finally generated code is totally customizable and the shown example is very opinionated. To enable your custom Templates you copy the files from the template folder to a folder on you local disk. Then you can customize them and pass the path of the folder as an argument like:

valgene --template-folder $PWD/my-custom-php-templates --spec petstore-expanded.yaml --option 'php.namespace:\My\PetStore\Api'

Further reading of variables available in templates you can find here

Installation #

the dart way:

pub global activate valgene_cli

Generating code for other languages #

as seen above there is a --template parameter that allows to switch the generated language/template.

valgene --template php5.5 --spec petstore-expanded.yaml --option 'php.namespace:\My\PetStore\Api'

In fact the code generators itself are just a couple of templates that getting rendered by the valgene engine. The template language itself is Mustache and therefore you can customize the code that is generated pretty easy.

Things to be done #

  • add support for API specs in other formats such as JSON
  • add support for a config file that lives in a own project to save the command line args
  • providing templates for other languages like Java
  • working on a IDE integration for VS Code and IntelliJ to automate things even further
  • full fledged package that can be run standalone (especially in the IDE for integration)

0.0.1 #

  • minimal working version, far away from feature complete

1.0.0 #

  • minimal working version, with bit more examples

1.0.1 #

  • implement openAPI default and allOf

1.0.2 #

  • implement template-folder cli argument to give customized templates into the engine

1.0.3 #

  • implement openAPI nullable on objects that plays well with default

example/README.md

Example 1 #

generate validator and DTO for the PetStore petstore-expanded.yaml

step 1 download the OpenAPI specification file: #

wget https://raw.githubusercontent.com/valgene/valgene-cli/master/example/petstore-expanded.yaml

step 2 run valgene and let the code generate: #

valgene --template php5.5 --spec petstore-expanded.yaml --option 'php.namespace:\My\PetStore\Api'

Example 2 Payload with array of Objects #

generate validator and DTO for the PetStore container-types.yaml that shows how an array of Objects is used.

step 1 download the OpenAPI specification file: #

wget https://raw.githubusercontent.com/valgene/valgene-cli/master/example/container-types.yaml

step 2 run valgene and let the code generate: #

valgene --template php5.5 --spec container-types.yaml --option 'php.namespace:\My\PetStore\Api'

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate valgene_cli

2. Use it

The package has the following executables:


$ valgene

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  valgene_cli: ^1.0.5

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:valgene_cli/valgene_cli.dart';
  
Version Uploaded Documentation Archive
1.0.5 Feb 8, 2019 Go to the documentation of valgene_cli 1.0.5 Download valgene_cli 1.0.5 archive
1.0.4 Feb 6, 2019 Go to the documentation of valgene_cli 1.0.4 Download valgene_cli 1.0.4 archive
1.0.3 Nov 26, 2018 Go to the documentation of valgene_cli 1.0.3 Download valgene_cli 1.0.3 archive
1.0.2 Nov 25, 2018 Go to the documentation of valgene_cli 1.0.2 Download valgene_cli 1.0.2 archive
1.0.1 Nov 24, 2018 Go to the documentation of valgene_cli 1.0.1 Download valgene_cli 1.0.1 archive
1.0.0 Nov 13, 2018 Go to the documentation of valgene_cli 1.0.0 Download valgene_cli 1.0.0 archive
0.0.1 Nov 13, 2018 Go to the documentation of valgene_cli 0.0.1 Download valgene_cli 0.0.1 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
94
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
48
Learn more about scoring.

We analyzed this package on Feb 14, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.1.0
  • pana: 0.12.13

Platforms

Detected platforms: other

Primary library: package:valgene_cli/valgene_cli.dart with components: io, mirrors.

Health issues and suggestions

Document public APIs. (-0.65 points)

167 out of 169 API elements have no dartdoc comment.Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API.

Fix lib/types.dart. (-5.36 points)

Analysis of lib/types.dart reported 11 hints, including:

line 41 col 7: Don't explicitly initialize variables to null.

line 41 col 20: Use = to separate a named parameter from its default value.

line 42 col 7: Don't explicitly initialize variables to null.

line 42 col 20: Use = to separate a named parameter from its default value.

line 43 col 7: Don't explicitly initialize variables to null.

Fix lib/parser.dart. (-0.50 points)

Analysis of lib/parser.dart reported 1 hint:

line 97 col 18: Don't explicitly initialize variables to null.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
args ^1.5.0 1.5.1
logging ^0.11.3+2 0.11.3+2
meta ^1.1.6 1.1.7
mustache ^1.0.2 1.1.1
recase ^2.0.0+1 2.0.1
yaml ^2.1.15 2.1.15
Transitive dependencies
charcode 1.1.2
collection 1.14.11
path 1.6.2
source_span 1.5.4
string_scanner 1.0.4
term_glyph 1.1.0
Dev dependencies
mockito ^3.0.0
test ^1.4.0
test_coverage ^0.2.0