Orpha  Leannon

Orpha Leannon

1617765879

Comprehensive Guide to Modules in Ruby 3

Ruby modules can appear to be very similar to Ruby classes. After going through this you’ll be able to:

  • Understand the difference between Classes and Modules in Ruby
  • Build out Ruby modules
  • Work with nested modules
  • Combine Classes and Modules
  • See how modules can be used in large-scale, production Rails applications

Source code:

https://github.com/jordanhudgens/ruby-3/blob/master/ruby_modules.rb

#ruby #ruby-on-rails

What is GEEK

Buddha Community

Comprehensive Guide to Modules in Ruby 3
Veronica  Roob

Veronica Roob

1653475560

A Pure PHP Implementation Of The MessagePack Serialization Format

msgpack.php

A pure PHP implementation of the MessagePack serialization format.

Features

Installation

The recommended way to install the library is through Composer:

composer require rybakit/msgpack

Usage

Packing

To pack values you can either use an instance of a Packer:

$packer = new Packer();
$packed = $packer->pack($value);

or call a static method on the MessagePack class:

$packed = MessagePack::pack($value);

In the examples above, the method pack automatically packs a value depending on its type. However, not all PHP types can be uniquely translated to MessagePack types. For example, the MessagePack format defines map and array types, which are represented by a single array type in PHP. By default, the packer will pack a PHP array as a MessagePack array if it has sequential numeric keys, starting from 0 and as a MessagePack map otherwise:

$mpArr1 = $packer->pack([1, 2]);               // MP array [1, 2]
$mpArr2 = $packer->pack([0 => 1, 1 => 2]);     // MP array [1, 2]
$mpMap1 = $packer->pack([0 => 1, 2 => 3]);     // MP map {0: 1, 2: 3}
$mpMap2 = $packer->pack([1 => 2, 2 => 3]);     // MP map {1: 2, 2: 3}
$mpMap3 = $packer->pack(['a' => 1, 'b' => 2]); // MP map {a: 1, b: 2}

However, sometimes you need to pack a sequential array as a MessagePack map. To do this, use the packMap method:

$mpMap = $packer->packMap([1, 2]); // {0: 1, 1: 2}

Here is a list of type-specific packing methods:

$packer->packNil();           // MP nil
$packer->packBool(true);      // MP bool
$packer->packInt(42);         // MP int
$packer->packFloat(M_PI);     // MP float (32 or 64)
$packer->packFloat32(M_PI);   // MP float 32
$packer->packFloat64(M_PI);   // MP float 64
$packer->packStr('foo');      // MP str
$packer->packBin("\x80");     // MP bin
$packer->packArray([1, 2]);   // MP array
$packer->packMap(['a' => 1]); // MP map
$packer->packExt(1, "\xaa");  // MP ext

Check the "Custom types" section below on how to pack custom types.

Packing options

The Packer object supports a number of bitmask-based options for fine-tuning the packing process (defaults are in bold):

NameDescription
FORCE_STRForces PHP strings to be packed as MessagePack UTF-8 strings
FORCE_BINForces PHP strings to be packed as MessagePack binary data
DETECT_STR_BINDetects MessagePack str/bin type automatically
  
FORCE_ARRForces PHP arrays to be packed as MessagePack arrays
FORCE_MAPForces PHP arrays to be packed as MessagePack maps
DETECT_ARR_MAPDetects MessagePack array/map type automatically
  
FORCE_FLOAT32Forces PHP floats to be packed as 32-bits MessagePack floats
FORCE_FLOAT64Forces PHP floats to be packed as 64-bits MessagePack floats

The type detection mode (DETECT_STR_BIN/DETECT_ARR_MAP) adds some overhead which can be noticed when you pack large (16- and 32-bit) arrays or strings. However, if you know the value type in advance (for example, you only work with UTF-8 strings or/and associative arrays), you can eliminate this overhead by forcing the packer to use the appropriate type, which will save it from running the auto-detection routine. Another option is to explicitly specify the value type. The library provides 2 auxiliary classes for this, Map and Bin. Check the "Custom types" section below for details.

Examples:

// detect str/bin type and pack PHP 64-bit floats (doubles) to MP 32-bit floats
$packer = new Packer(PackOptions::DETECT_STR_BIN | PackOptions::FORCE_FLOAT32);

// these will throw MessagePack\Exception\InvalidOptionException
$packer = new Packer(PackOptions::FORCE_STR | PackOptions::FORCE_BIN);
$packer = new Packer(PackOptions::FORCE_FLOAT32 | PackOptions::FORCE_FLOAT64);

Unpacking

To unpack data you can either use an instance of a BufferUnpacker:

$unpacker = new BufferUnpacker();

$unpacker->reset($packed);
$value = $unpacker->unpack();

or call a static method on the MessagePack class:

$value = MessagePack::unpack($packed);

If the packed data is received in chunks (e.g. when reading from a stream), use the tryUnpack method, which attempts to unpack data and returns an array of unpacked messages (if any) instead of throwing an InsufficientDataException:

while ($chunk = ...) {
    $unpacker->append($chunk);
    if ($messages = $unpacker->tryUnpack()) {
        return $messages;
    }
}

If you want to unpack from a specific position in a buffer, use seek:

$unpacker->seek(42); // set position equal to 42 bytes
$unpacker->seek(-8); // set position to 8 bytes before the end of the buffer

To skip bytes from the current position, use skip:

$unpacker->skip(10); // set position to 10 bytes ahead of the current position

To get the number of remaining (unread) bytes in the buffer:

$unreadBytesCount = $unpacker->getRemainingCount();

To check whether the buffer has unread data:

$hasUnreadBytes = $unpacker->hasRemaining();

If needed, you can remove already read data from the buffer by calling:

$releasedBytesCount = $unpacker->release();

With the read method you can read raw (packed) data:

$packedData = $unpacker->read(2); // read 2 bytes

Besides the above methods BufferUnpacker provides type-specific unpacking methods, namely:

$unpacker->unpackNil();   // PHP null
$unpacker->unpackBool();  // PHP bool
$unpacker->unpackInt();   // PHP int
$unpacker->unpackFloat(); // PHP float
$unpacker->unpackStr();   // PHP UTF-8 string
$unpacker->unpackBin();   // PHP binary string
$unpacker->unpackArray(); // PHP sequential array
$unpacker->unpackMap();   // PHP associative array
$unpacker->unpackExt();   // PHP MessagePack\Type\Ext object

Unpacking options

The BufferUnpacker object supports a number of bitmask-based options for fine-tuning the unpacking process (defaults are in bold):

NameDescription
BIGINT_AS_STRConverts overflowed integers to strings [1]
BIGINT_AS_GMPConverts overflowed integers to GMP objects [2]
BIGINT_AS_DECConverts overflowed integers to Decimal\Decimal objects [3]

1. The binary MessagePack format has unsigned 64-bit as its largest integer data type, but PHP does not support such integers, which means that an overflow can occur during unpacking.

2. Make sure the GMP extension is enabled.

3. Make sure the Decimal extension is enabled.

Examples:

$packedUint64 = "\xcf"."\xff\xff\xff\xff"."\xff\xff\xff\xff";

$unpacker = new BufferUnpacker($packedUint64);
var_dump($unpacker->unpack()); // string(20) "18446744073709551615"

$unpacker = new BufferUnpacker($packedUint64, UnpackOptions::BIGINT_AS_GMP);
var_dump($unpacker->unpack()); // object(GMP) {...}

$unpacker = new BufferUnpacker($packedUint64, UnpackOptions::BIGINT_AS_DEC);
var_dump($unpacker->unpack()); // object(Decimal\Decimal) {...}

Custom types

In addition to the basic types, the library provides functionality to serialize and deserialize arbitrary types. This can be done in several ways, depending on your use case. Let's take a look at them.

Type objects

If you need to serialize an instance of one of your classes into one of the basic MessagePack types, the best way to do this is to implement the CanBePacked interface in the class. A good example of such a class is the Map type class that comes with the library. This type is useful when you want to explicitly specify that a given PHP array should be packed as a MessagePack map without triggering an automatic type detection routine:

$packer = new Packer();

$packedMap = $packer->pack(new Map([1, 2, 3]));
$packedArray = $packer->pack([1, 2, 3]);

More type examples can be found in the src/Type directory.

Type transformers

As with type objects, type transformers are only responsible for serializing values. They should be used when you need to serialize a value that does not implement the CanBePacked interface. Examples of such values could be instances of built-in or third-party classes that you don't own, or non-objects such as resources.

A transformer class must implement the CanPack interface. To use a transformer, it must first be registered in the packer. Here is an example of how to serialize PHP streams into the MessagePack bin format type using one of the supplied transformers, StreamTransformer:

$packer = new Packer(null, [new StreamTransformer()]);

$packedBin = $packer->pack(fopen('/path/to/file', 'r+'));

More type transformer examples can be found in the src/TypeTransformer directory.

Extensions

In contrast to the cases described above, extensions are intended to handle extension types and are responsible for both serialization and deserialization of values (types).

An extension class must implement the Extension interface. To use an extension, it must first be registered in the packer and the unpacker.

The MessagePack specification divides extension types into two groups: predefined and application-specific. Currently, there is only one predefined type in the specification, Timestamp.

Timestamp

The Timestamp extension type is a predefined type. Support for this type in the library is done through the TimestampExtension class. This class is responsible for handling Timestamp objects, which represent the number of seconds and optional adjustment in nanoseconds:

$timestampExtension = new TimestampExtension();

$packer = new Packer();
$packer = $packer->extendWith($timestampExtension);

$unpacker = new BufferUnpacker();
$unpacker = $unpacker->extendWith($timestampExtension);

$packedTimestamp = $packer->pack(Timestamp::now());
$timestamp = $unpacker->reset($packedTimestamp)->unpack();

$seconds = $timestamp->getSeconds();
$nanoseconds = $timestamp->getNanoseconds();

When using the MessagePack class, the Timestamp extension is already registered:

$packedTimestamp = MessagePack::pack(Timestamp::now());
$timestamp = MessagePack::unpack($packedTimestamp);

Application-specific extensions

In addition, the format can be extended with your own types. For example, to make the built-in PHP DateTime objects first-class citizens in your code, you can create a corresponding extension, as shown in the example. Please note, that custom extensions have to be registered with a unique extension ID (an integer from 0 to 127).

More extension examples can be found in the examples/MessagePack directory.

To learn more about how extension types can be useful, check out this article.

Exceptions

If an error occurs during packing/unpacking, a PackingFailedException or an UnpackingFailedException will be thrown, respectively. In addition, an InsufficientDataException can be thrown during unpacking.

An InvalidOptionException will be thrown in case an invalid option (or a combination of mutually exclusive options) is used.

Tests

Run tests as follows:

vendor/bin/phpunit

Also, if you already have Docker installed, you can run the tests in a docker container. First, create a container:

./dockerfile.sh | docker build -t msgpack -

The command above will create a container named msgpack with PHP 8.1 runtime. You may change the default runtime by defining the PHP_IMAGE environment variable:

PHP_IMAGE='php:8.0-cli' ./dockerfile.sh | docker build -t msgpack -

See a list of various images here.

Then run the unit tests:

docker run --rm -v $PWD:/msgpack -w /msgpack msgpack

Fuzzing

To ensure that the unpacking works correctly with malformed/semi-malformed data, you can use a testing technique called Fuzzing. The library ships with a help file (target) for PHP-Fuzzer and can be used as follows:

php-fuzzer fuzz tests/fuzz_buffer_unpacker.php

Performance

To check performance, run:

php -n -dzend_extension=opcache.so \
-dpcre.jit=1 -dopcache.enable=1 -dopcache.enable_cli=1 \
tests/bench.php

Example output

Filter: MessagePack\Tests\Perf\Filter\ListFilter
Rounds: 3
Iterations: 100000

=============================================
Test/Target            Packer  BufferUnpacker
---------------------------------------------
nil .................. 0.0030 ........ 0.0139
false ................ 0.0037 ........ 0.0144
true ................. 0.0040 ........ 0.0137
7-bit uint #1 ........ 0.0052 ........ 0.0120
7-bit uint #2 ........ 0.0059 ........ 0.0114
7-bit uint #3 ........ 0.0061 ........ 0.0119
5-bit sint #1 ........ 0.0067 ........ 0.0126
5-bit sint #2 ........ 0.0064 ........ 0.0132
5-bit sint #3 ........ 0.0066 ........ 0.0135
8-bit uint #1 ........ 0.0078 ........ 0.0200
8-bit uint #2 ........ 0.0077 ........ 0.0212
8-bit uint #3 ........ 0.0086 ........ 0.0203
16-bit uint #1 ....... 0.0111 ........ 0.0271
16-bit uint #2 ....... 0.0115 ........ 0.0260
16-bit uint #3 ....... 0.0103 ........ 0.0273
32-bit uint #1 ....... 0.0116 ........ 0.0326
32-bit uint #2 ....... 0.0118 ........ 0.0332
32-bit uint #3 ....... 0.0127 ........ 0.0325
64-bit uint #1 ....... 0.0140 ........ 0.0277
64-bit uint #2 ....... 0.0134 ........ 0.0294
64-bit uint #3 ....... 0.0134 ........ 0.0281
8-bit int #1 ......... 0.0086 ........ 0.0241
8-bit int #2 ......... 0.0089 ........ 0.0225
8-bit int #3 ......... 0.0085 ........ 0.0229
16-bit int #1 ........ 0.0118 ........ 0.0280
16-bit int #2 ........ 0.0121 ........ 0.0270
16-bit int #3 ........ 0.0109 ........ 0.0274
32-bit int #1 ........ 0.0128 ........ 0.0346
32-bit int #2 ........ 0.0118 ........ 0.0339
32-bit int #3 ........ 0.0135 ........ 0.0368
64-bit int #1 ........ 0.0138 ........ 0.0276
64-bit int #2 ........ 0.0132 ........ 0.0286
64-bit int #3 ........ 0.0137 ........ 0.0274
64-bit int #4 ........ 0.0180 ........ 0.0285
64-bit float #1 ...... 0.0134 ........ 0.0284
64-bit float #2 ...... 0.0125 ........ 0.0275
64-bit float #3 ...... 0.0126 ........ 0.0283
fix string #1 ........ 0.0035 ........ 0.0133
fix string #2 ........ 0.0094 ........ 0.0216
fix string #3 ........ 0.0094 ........ 0.0222
fix string #4 ........ 0.0091 ........ 0.0241
8-bit string #1 ...... 0.0122 ........ 0.0301
8-bit string #2 ...... 0.0118 ........ 0.0304
8-bit string #3 ...... 0.0119 ........ 0.0315
16-bit string #1 ..... 0.0150 ........ 0.0388
16-bit string #2 ..... 0.1545 ........ 0.1665
32-bit string ........ 0.1570 ........ 0.1756
wide char string #1 .. 0.0091 ........ 0.0236
wide char string #2 .. 0.0122 ........ 0.0313
8-bit binary #1 ...... 0.0100 ........ 0.0302
8-bit binary #2 ...... 0.0123 ........ 0.0324
8-bit binary #3 ...... 0.0126 ........ 0.0327
16-bit binary ........ 0.0168 ........ 0.0372
32-bit binary ........ 0.1588 ........ 0.1754
fix array #1 ......... 0.0042 ........ 0.0131
fix array #2 ......... 0.0294 ........ 0.0367
fix array #3 ......... 0.0412 ........ 0.0472
16-bit array #1 ...... 0.1378 ........ 0.1596
16-bit array #2 ........... S ............. S
32-bit array .............. S ............. S
complex array ........ 0.1865 ........ 0.2283
fix map #1 ........... 0.0725 ........ 0.1048
fix map #2 ........... 0.0319 ........ 0.0405
fix map #3 ........... 0.0356 ........ 0.0665
fix map #4 ........... 0.0465 ........ 0.0497
16-bit map #1 ........ 0.2540 ........ 0.3028
16-bit map #2 ............. S ............. S
32-bit map ................ S ............. S
complex map .......... 0.2372 ........ 0.2710
fixext 1 ............. 0.0283 ........ 0.0358
fixext 2 ............. 0.0291 ........ 0.0371
fixext 4 ............. 0.0302 ........ 0.0355
fixext 8 ............. 0.0288 ........ 0.0384
fixext 16 ............ 0.0293 ........ 0.0359
8-bit ext ............ 0.0302 ........ 0.0439
16-bit ext ........... 0.0334 ........ 0.0499
32-bit ext ........... 0.1845 ........ 0.1888
32-bit timestamp #1 .. 0.0337 ........ 0.0547
32-bit timestamp #2 .. 0.0335 ........ 0.0560
64-bit timestamp #1 .. 0.0371 ........ 0.0575
64-bit timestamp #2 .. 0.0374 ........ 0.0542
64-bit timestamp #3 .. 0.0356 ........ 0.0533
96-bit timestamp #1 .. 0.0362 ........ 0.0699
96-bit timestamp #2 .. 0.0381 ........ 0.0701
96-bit timestamp #3 .. 0.0367 ........ 0.0687
=============================================
Total                  2.7618          4.0820
Skipped                     4               4
Failed                      0               0
Ignored                     0               0

With JIT:

php -n -dzend_extension=opcache.so \
-dpcre.jit=1 -dopcache.jit_buffer_size=64M -dopcache.jit=tracing -dopcache.enable=1 -dopcache.enable_cli=1 \
tests/bench.php

Example output

Filter: MessagePack\Tests\Perf\Filter\ListFilter
Rounds: 3
Iterations: 100000

=============================================
Test/Target            Packer  BufferUnpacker
---------------------------------------------
nil .................. 0.0005 ........ 0.0054
false ................ 0.0004 ........ 0.0059
true ................. 0.0004 ........ 0.0059
7-bit uint #1 ........ 0.0010 ........ 0.0047
7-bit uint #2 ........ 0.0010 ........ 0.0046
7-bit uint #3 ........ 0.0010 ........ 0.0046
5-bit sint #1 ........ 0.0025 ........ 0.0046
5-bit sint #2 ........ 0.0023 ........ 0.0046
5-bit sint #3 ........ 0.0024 ........ 0.0045
8-bit uint #1 ........ 0.0043 ........ 0.0081
8-bit uint #2 ........ 0.0043 ........ 0.0079
8-bit uint #3 ........ 0.0041 ........ 0.0080
16-bit uint #1 ....... 0.0064 ........ 0.0095
16-bit uint #2 ....... 0.0064 ........ 0.0091
16-bit uint #3 ....... 0.0064 ........ 0.0094
32-bit uint #1 ....... 0.0085 ........ 0.0114
32-bit uint #2 ....... 0.0077 ........ 0.0122
32-bit uint #3 ....... 0.0077 ........ 0.0120
64-bit uint #1 ....... 0.0085 ........ 0.0159
64-bit uint #2 ....... 0.0086 ........ 0.0157
64-bit uint #3 ....... 0.0086 ........ 0.0158
8-bit int #1 ......... 0.0042 ........ 0.0080
8-bit int #2 ......... 0.0042 ........ 0.0080
8-bit int #3 ......... 0.0042 ........ 0.0081
16-bit int #1 ........ 0.0065 ........ 0.0095
16-bit int #2 ........ 0.0065 ........ 0.0090
16-bit int #3 ........ 0.0056 ........ 0.0085
32-bit int #1 ........ 0.0067 ........ 0.0107
32-bit int #2 ........ 0.0066 ........ 0.0106
32-bit int #3 ........ 0.0063 ........ 0.0104
64-bit int #1 ........ 0.0072 ........ 0.0162
64-bit int #2 ........ 0.0073 ........ 0.0174
64-bit int #3 ........ 0.0072 ........ 0.0164
64-bit int #4 ........ 0.0077 ........ 0.0161
64-bit float #1 ...... 0.0053 ........ 0.0135
64-bit float #2 ...... 0.0053 ........ 0.0135
64-bit float #3 ...... 0.0052 ........ 0.0135
fix string #1 ....... -0.0002 ........ 0.0044
fix string #2 ........ 0.0035 ........ 0.0067
fix string #3 ........ 0.0035 ........ 0.0077
fix string #4 ........ 0.0033 ........ 0.0078
8-bit string #1 ...... 0.0059 ........ 0.0110
8-bit string #2 ...... 0.0063 ........ 0.0121
8-bit string #3 ...... 0.0064 ........ 0.0124
16-bit string #1 ..... 0.0099 ........ 0.0146
16-bit string #2 ..... 0.1522 ........ 0.1474
32-bit string ........ 0.1511 ........ 0.1483
wide char string #1 .. 0.0039 ........ 0.0084
wide char string #2 .. 0.0073 ........ 0.0123
8-bit binary #1 ...... 0.0040 ........ 0.0112
8-bit binary #2 ...... 0.0075 ........ 0.0123
8-bit binary #3 ...... 0.0077 ........ 0.0129
16-bit binary ........ 0.0096 ........ 0.0145
32-bit binary ........ 0.1535 ........ 0.1479
fix array #1 ......... 0.0008 ........ 0.0061
fix array #2 ......... 0.0121 ........ 0.0165
fix array #3 ......... 0.0193 ........ 0.0222
16-bit array #1 ...... 0.0607 ........ 0.0479
16-bit array #2 ........... S ............. S
32-bit array .............. S ............. S
complex array ........ 0.0749 ........ 0.0824
fix map #1 ........... 0.0329 ........ 0.0431
fix map #2 ........... 0.0161 ........ 0.0189
fix map #3 ........... 0.0205 ........ 0.0262
fix map #4 ........... 0.0252 ........ 0.0205
16-bit map #1 ........ 0.1016 ........ 0.0927
16-bit map #2 ............. S ............. S
32-bit map ................ S ............. S
complex map .......... 0.1096 ........ 0.1030
fixext 1 ............. 0.0157 ........ 0.0161
fixext 2 ............. 0.0175 ........ 0.0183
fixext 4 ............. 0.0156 ........ 0.0185
fixext 8 ............. 0.0163 ........ 0.0184
fixext 16 ............ 0.0164 ........ 0.0182
8-bit ext ............ 0.0158 ........ 0.0207
16-bit ext ........... 0.0203 ........ 0.0219
32-bit ext ........... 0.1614 ........ 0.1539
32-bit timestamp #1 .. 0.0195 ........ 0.0249
32-bit timestamp #2 .. 0.0188 ........ 0.0260
64-bit timestamp #1 .. 0.0207 ........ 0.0281
64-bit timestamp #2 .. 0.0212 ........ 0.0291
64-bit timestamp #3 .. 0.0207 ........ 0.0295
96-bit timestamp #1 .. 0.0222 ........ 0.0358
96-bit timestamp #2 .. 0.0228 ........ 0.0353
96-bit timestamp #3 .. 0.0210 ........ 0.0319
=============================================
Total                  1.6432          1.9674
Skipped                     4               4
Failed                      0               0
Ignored                     0               0

You may change default benchmark settings by defining the following environment variables:

NameDefault
MP_BENCH_TARGETSpure_p,pure_u, see a list of available targets
MP_BENCH_ITERATIONS100_000
MP_BENCH_DURATIONnot set
MP_BENCH_ROUNDS3
MP_BENCH_TESTS-@slow, see a list of available tests

For example:

export MP_BENCH_TARGETS=pure_p
export MP_BENCH_ITERATIONS=1000000
export MP_BENCH_ROUNDS=5
# a comma separated list of test names
export MP_BENCH_TESTS='complex array, complex map'
# or a group name
# export MP_BENCH_TESTS='-@slow' // @pecl_comp
# or a regexp
# export MP_BENCH_TESTS='/complex (array|map)/'

Another example, benchmarking both the library and the PECL extension:

MP_BENCH_TARGETS=pure_p,pure_u,pecl_p,pecl_u \
php -n -dextension=msgpack.so -dzend_extension=opcache.so \
-dpcre.jit=1 -dopcache.enable=1 -dopcache.enable_cli=1 \
tests/bench.php

Example output

Filter: MessagePack\Tests\Perf\Filter\ListFilter
Rounds: 3
Iterations: 100000

===========================================================================
Test/Target            Packer  BufferUnpacker  msgpack_pack  msgpack_unpack
---------------------------------------------------------------------------
nil .................. 0.0031 ........ 0.0141 ...... 0.0055 ........ 0.0064
false ................ 0.0039 ........ 0.0154 ...... 0.0056 ........ 0.0053
true ................. 0.0038 ........ 0.0139 ...... 0.0056 ........ 0.0044
7-bit uint #1 ........ 0.0061 ........ 0.0110 ...... 0.0059 ........ 0.0046
7-bit uint #2 ........ 0.0065 ........ 0.0119 ...... 0.0042 ........ 0.0029
7-bit uint #3 ........ 0.0054 ........ 0.0117 ...... 0.0045 ........ 0.0025
5-bit sint #1 ........ 0.0047 ........ 0.0103 ...... 0.0038 ........ 0.0022
5-bit sint #2 ........ 0.0048 ........ 0.0117 ...... 0.0038 ........ 0.0022
5-bit sint #3 ........ 0.0046 ........ 0.0102 ...... 0.0038 ........ 0.0023
8-bit uint #1 ........ 0.0063 ........ 0.0174 ...... 0.0039 ........ 0.0031
8-bit uint #2 ........ 0.0063 ........ 0.0167 ...... 0.0040 ........ 0.0029
8-bit uint #3 ........ 0.0063 ........ 0.0168 ...... 0.0039 ........ 0.0030
16-bit uint #1 ....... 0.0092 ........ 0.0222 ...... 0.0049 ........ 0.0030
16-bit uint #2 ....... 0.0096 ........ 0.0227 ...... 0.0042 ........ 0.0046
16-bit uint #3 ....... 0.0123 ........ 0.0274 ...... 0.0059 ........ 0.0051
32-bit uint #1 ....... 0.0136 ........ 0.0331 ...... 0.0060 ........ 0.0048
32-bit uint #2 ....... 0.0130 ........ 0.0336 ...... 0.0070 ........ 0.0048
32-bit uint #3 ....... 0.0127 ........ 0.0329 ...... 0.0051 ........ 0.0048
64-bit uint #1 ....... 0.0126 ........ 0.0268 ...... 0.0055 ........ 0.0049
64-bit uint #2 ....... 0.0135 ........ 0.0281 ...... 0.0052 ........ 0.0046
64-bit uint #3 ....... 0.0131 ........ 0.0274 ...... 0.0069 ........ 0.0044
8-bit int #1 ......... 0.0077 ........ 0.0236 ...... 0.0058 ........ 0.0044
8-bit int #2 ......... 0.0087 ........ 0.0244 ...... 0.0058 ........ 0.0048
8-bit int #3 ......... 0.0084 ........ 0.0241 ...... 0.0055 ........ 0.0049
16-bit int #1 ........ 0.0112 ........ 0.0271 ...... 0.0048 ........ 0.0045
16-bit int #2 ........ 0.0124 ........ 0.0292 ...... 0.0057 ........ 0.0049
16-bit int #3 ........ 0.0118 ........ 0.0270 ...... 0.0058 ........ 0.0050
32-bit int #1 ........ 0.0137 ........ 0.0366 ...... 0.0058 ........ 0.0051
32-bit int #2 ........ 0.0133 ........ 0.0366 ...... 0.0056 ........ 0.0049
32-bit int #3 ........ 0.0129 ........ 0.0350 ...... 0.0052 ........ 0.0048
64-bit int #1 ........ 0.0145 ........ 0.0254 ...... 0.0034 ........ 0.0025
64-bit int #2 ........ 0.0097 ........ 0.0214 ...... 0.0034 ........ 0.0025
64-bit int #3 ........ 0.0096 ........ 0.0287 ...... 0.0059 ........ 0.0050
64-bit int #4 ........ 0.0143 ........ 0.0277 ...... 0.0059 ........ 0.0046
64-bit float #1 ...... 0.0134 ........ 0.0281 ...... 0.0057 ........ 0.0052
64-bit float #2 ...... 0.0141 ........ 0.0281 ...... 0.0057 ........ 0.0050
64-bit float #3 ...... 0.0144 ........ 0.0282 ...... 0.0057 ........ 0.0050
fix string #1 ........ 0.0036 ........ 0.0143 ...... 0.0066 ........ 0.0053
fix string #2 ........ 0.0107 ........ 0.0222 ...... 0.0065 ........ 0.0068
fix string #3 ........ 0.0116 ........ 0.0245 ...... 0.0063 ........ 0.0069
fix string #4 ........ 0.0105 ........ 0.0253 ...... 0.0083 ........ 0.0077
8-bit string #1 ...... 0.0126 ........ 0.0318 ...... 0.0075 ........ 0.0088
8-bit string #2 ...... 0.0121 ........ 0.0295 ...... 0.0076 ........ 0.0086
8-bit string #3 ...... 0.0125 ........ 0.0293 ...... 0.0130 ........ 0.0093
16-bit string #1 ..... 0.0159 ........ 0.0368 ...... 0.0117 ........ 0.0086
16-bit string #2 ..... 0.1547 ........ 0.1686 ...... 0.1516 ........ 0.1373
32-bit string ........ 0.1558 ........ 0.1729 ...... 0.1511 ........ 0.1396
wide char string #1 .. 0.0098 ........ 0.0237 ...... 0.0066 ........ 0.0065
wide char string #2 .. 0.0128 ........ 0.0291 ...... 0.0061 ........ 0.0082
8-bit binary #1 ........... I ............. I ........... F ............. I
8-bit binary #2 ........... I ............. I ........... F ............. I
8-bit binary #3 ........... I ............. I ........... F ............. I
16-bit binary ............. I ............. I ........... F ............. I
32-bit binary ............. I ............. I ........... F ............. I
fix array #1 ......... 0.0040 ........ 0.0129 ...... 0.0120 ........ 0.0058
fix array #2 ......... 0.0279 ........ 0.0390 ...... 0.0143 ........ 0.0165
fix array #3 ......... 0.0415 ........ 0.0463 ...... 0.0162 ........ 0.0187
16-bit array #1 ...... 0.1349 ........ 0.1628 ...... 0.0334 ........ 0.0341
16-bit array #2 ........... S ............. S ........... S ............. S
32-bit array .............. S ............. S ........... S ............. S
complex array ............. I ............. I ........... F ............. F
fix map #1 ................ I ............. I ........... F ............. I
fix map #2 ........... 0.0345 ........ 0.0391 ...... 0.0143 ........ 0.0168
fix map #3 ................ I ............. I ........... F ............. I
fix map #4 ........... 0.0459 ........ 0.0473 ...... 0.0151 ........ 0.0163
16-bit map #1 ........ 0.2518 ........ 0.2962 ...... 0.0400 ........ 0.0490
16-bit map #2 ............. S ............. S ........... S ............. S
32-bit map ................ S ............. S ........... S ............. S
complex map .......... 0.2380 ........ 0.2682 ...... 0.0545 ........ 0.0579
fixext 1 .................. I ............. I ........... F ............. F
fixext 2 .................. I ............. I ........... F ............. F
fixext 4 .................. I ............. I ........... F ............. F
fixext 8 .................. I ............. I ........... F ............. F
fixext 16 ................. I ............. I ........... F ............. F
8-bit ext ................. I ............. I ........... F ............. F
16-bit ext ................ I ............. I ........... F ............. F
32-bit ext ................ I ............. I ........... F ............. F
32-bit timestamp #1 ....... I ............. I ........... F ............. F
32-bit timestamp #2 ....... I ............. I ........... F ............. F
64-bit timestamp #1 ....... I ............. I ........... F ............. F
64-bit timestamp #2 ....... I ............. I ........... F ............. F
64-bit timestamp #3 ....... I ............. I ........... F ............. F
96-bit timestamp #1 ....... I ............. I ........... F ............. F
96-bit timestamp #2 ....... I ............. I ........... F ............. F
96-bit timestamp #3 ....... I ............. I ........... F ............. F
===========================================================================
Total                  1.5625          2.3866        0.7735          0.7243
Skipped                     4               4             4               4
Failed                      0               0            24              17
Ignored                    24              24             0               7

With JIT:

MP_BENCH_TARGETS=pure_p,pure_u,pecl_p,pecl_u \
php -n -dextension=msgpack.so -dzend_extension=opcache.so \
-dpcre.jit=1 -dopcache.jit_buffer_size=64M -dopcache.jit=tracing -dopcache.enable=1 -dopcache.enable_cli=1 \
tests/bench.php

Example output

Filter: MessagePack\Tests\Perf\Filter\ListFilter
Rounds: 3
Iterations: 100000

===========================================================================
Test/Target            Packer  BufferUnpacker  msgpack_pack  msgpack_unpack
---------------------------------------------------------------------------
nil .................. 0.0001 ........ 0.0052 ...... 0.0053 ........ 0.0042
false ................ 0.0007 ........ 0.0060 ...... 0.0057 ........ 0.0043
true ................. 0.0008 ........ 0.0060 ...... 0.0056 ........ 0.0041
7-bit uint #1 ........ 0.0031 ........ 0.0046 ...... 0.0062 ........ 0.0041
7-bit uint #2 ........ 0.0021 ........ 0.0043 ...... 0.0062 ........ 0.0041
7-bit uint #3 ........ 0.0022 ........ 0.0044 ...... 0.0061 ........ 0.0040
5-bit sint #1 ........ 0.0030 ........ 0.0048 ...... 0.0062 ........ 0.0040
5-bit sint #2 ........ 0.0032 ........ 0.0046 ...... 0.0062 ........ 0.0040
5-bit sint #3 ........ 0.0031 ........ 0.0046 ...... 0.0062 ........ 0.0040
8-bit uint #1 ........ 0.0054 ........ 0.0079 ...... 0.0062 ........ 0.0050
8-bit uint #2 ........ 0.0051 ........ 0.0079 ...... 0.0064 ........ 0.0044
8-bit uint #3 ........ 0.0051 ........ 0.0082 ...... 0.0062 ........ 0.0044
16-bit uint #1 ....... 0.0077 ........ 0.0094 ...... 0.0065 ........ 0.0045
16-bit uint #2 ....... 0.0077 ........ 0.0094 ...... 0.0063 ........ 0.0045
16-bit uint #3 ....... 0.0077 ........ 0.0095 ...... 0.0064 ........ 0.0047
32-bit uint #1 ....... 0.0088 ........ 0.0119 ...... 0.0063 ........ 0.0043
32-bit uint #2 ....... 0.0089 ........ 0.0117 ...... 0.0062 ........ 0.0039
32-bit uint #3 ....... 0.0089 ........ 0.0118 ...... 0.0063 ........ 0.0044
64-bit uint #1 ....... 0.0097 ........ 0.0155 ...... 0.0063 ........ 0.0045
64-bit uint #2 ....... 0.0095 ........ 0.0153 ...... 0.0061 ........ 0.0045
64-bit uint #3 ....... 0.0096 ........ 0.0156 ...... 0.0063 ........ 0.0047
8-bit int #1 ......... 0.0053 ........ 0.0083 ...... 0.0062 ........ 0.0044
8-bit int #2 ......... 0.0052 ........ 0.0080 ...... 0.0062 ........ 0.0044
8-bit int #3 ......... 0.0052 ........ 0.0080 ...... 0.0062 ........ 0.0043
16-bit int #1 ........ 0.0089 ........ 0.0097 ...... 0.0069 ........ 0.0046
16-bit int #2 ........ 0.0075 ........ 0.0093 ...... 0.0063 ........ 0.0043
16-bit int #3 ........ 0.0075 ........ 0.0094 ...... 0.0062 ........ 0.0046
32-bit int #1 ........ 0.0086 ........ 0.0122 ...... 0.0063 ........ 0.0044
32-bit int #2 ........ 0.0087 ........ 0.0120 ...... 0.0066 ........ 0.0046
32-bit int #3 ........ 0.0086 ........ 0.0121 ...... 0.0060 ........ 0.0044
64-bit int #1 ........ 0.0096 ........ 0.0149 ...... 0.0060 ........ 0.0045
64-bit int #2 ........ 0.0096 ........ 0.0157 ...... 0.0062 ........ 0.0044
64-bit int #3 ........ 0.0096 ........ 0.0160 ...... 0.0063 ........ 0.0046
64-bit int #4 ........ 0.0097 ........ 0.0157 ...... 0.0061 ........ 0.0044
64-bit float #1 ...... 0.0079 ........ 0.0153 ...... 0.0056 ........ 0.0044
64-bit float #2 ...... 0.0079 ........ 0.0152 ...... 0.0057 ........ 0.0045
64-bit float #3 ...... 0.0079 ........ 0.0155 ...... 0.0057 ........ 0.0044
fix string #1 ........ 0.0010 ........ 0.0045 ...... 0.0071 ........ 0.0044
fix string #2 ........ 0.0048 ........ 0.0075 ...... 0.0070 ........ 0.0060
fix string #3 ........ 0.0048 ........ 0.0086 ...... 0.0068 ........ 0.0060
fix string #4 ........ 0.0050 ........ 0.0088 ...... 0.0070 ........ 0.0059
8-bit string #1 ...... 0.0081 ........ 0.0129 ...... 0.0069 ........ 0.0062
8-bit string #2 ...... 0.0086 ........ 0.0128 ...... 0.0069 ........ 0.0065
8-bit string #3 ...... 0.0086 ........ 0.0126 ...... 0.0115 ........ 0.0065
16-bit string #1 ..... 0.0105 ........ 0.0137 ...... 0.0128 ........ 0.0068
16-bit string #2 ..... 0.1510 ........ 0.1486 ...... 0.1526 ........ 0.1391
32-bit string ........ 0.1517 ........ 0.1475 ...... 0.1504 ........ 0.1370
wide char string #1 .. 0.0044 ........ 0.0085 ...... 0.0067 ........ 0.0057
wide char string #2 .. 0.0081 ........ 0.0125 ...... 0.0069 ........ 0.0063
8-bit binary #1 ........... I ............. I ........... F ............. I
8-bit binary #2 ........... I ............. I ........... F ............. I
8-bit binary #3 ........... I ............. I ........... F ............. I
16-bit binary ............. I ............. I ........... F ............. I
32-bit binary ............. I ............. I ........... F ............. I
fix array #1 ......... 0.0014 ........ 0.0059 ...... 0.0132 ........ 0.0055
fix array #2 ......... 0.0146 ........ 0.0156 ...... 0.0155 ........ 0.0148
fix array #3 ......... 0.0211 ........ 0.0229 ...... 0.0179 ........ 0.0180
16-bit array #1 ...... 0.0673 ........ 0.0498 ...... 0.0343 ........ 0.0388
16-bit array #2 ........... S ............. S ........... S ............. S
32-bit array .............. S ............. S ........... S ............. S
complex array ............. I ............. I ........... F ............. F
fix map #1 ................ I ............. I ........... F ............. I
fix map #2 ........... 0.0148 ........ 0.0180 ...... 0.0156 ........ 0.0179
fix map #3 ................ I ............. I ........... F ............. I
fix map #4 ........... 0.0252 ........ 0.0201 ...... 0.0214 ........ 0.0167
16-bit map #1 ........ 0.1027 ........ 0.0836 ...... 0.0388 ........ 0.0510
16-bit map #2 ............. S ............. S ........... S ............. S
32-bit map ................ S ............. S ........... S ............. S
complex map .......... 0.1104 ........ 0.1010 ...... 0.0556 ........ 0.0602
fixext 1 .................. I ............. I ........... F ............. F
fixext 2 .................. I ............. I ........... F ............. F
fixext 4 .................. I ............. I ........... F ............. F
fixext 8 .................. I ............. I ........... F ............. F
fixext 16 ................. I ............. I ........... F ............. F
8-bit ext ................. I ............. I ........... F ............. F
16-bit ext ................ I ............. I ........... F ............. F
32-bit ext ................ I ............. I ........... F ............. F
32-bit timestamp #1 ....... I ............. I ........... F ............. F
32-bit timestamp #2 ....... I ............. I ........... F ............. F
64-bit timestamp #1 ....... I ............. I ........... F ............. F
64-bit timestamp #2 ....... I ............. I ........... F ............. F
64-bit timestamp #3 ....... I ............. I ........... F ............. F
96-bit timestamp #1 ....... I ............. I ........... F ............. F
96-bit timestamp #2 ....... I ............. I ........... F ............. F
96-bit timestamp #3 ....... I ............. I ........... F ............. F
===========================================================================
Total                  0.9642          1.0909        0.8224          0.7213
Skipped                     4               4             4               4
Failed                      0               0            24              17
Ignored                    24              24             0               7

Note that the msgpack extension (v2.1.2) doesn't support ext, bin and UTF-8 str types.

License

The library is released under the MIT License. See the bundled LICENSE file for details.

Author: rybakit
Source Code: https://github.com/rybakit/msgpack.php
License: MIT License

#php 

A Wrapper for Sembast and SQFlite to Enable Easy

FHIR_DB

This is really just a wrapper around Sembast_SQFLite - so all of the heavy lifting was done by Alex Tekartik. I highly recommend that if you have any questions about working with this package that you take a look at Sembast. He's also just a super nice guy, and even answered a question for me when I was deciding which sembast version to use. As usual, ResoCoder also has a good tutorial.

I have an interest in low-resource settings and thus a specific reason to be able to store data offline. To encourage this use, there are a number of other packages I have created based around the data format FHIR. FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of this product by HL7.

Using the Db

So, while not absolutely necessary, I highly recommend that you use some sort of interface class. This adds the benefit of more easily handling errors, plus if you change to a different database in the future, you don't have to change the rest of your app, just the interface.

I've used something like this in my projects:

class IFhirDb {
  IFhirDb();
  final ResourceDao resourceDao = ResourceDao();

  Future<Either<DbFailure, Resource>> save(Resource resource) async {
    Resource resultResource;
    try {
      resultResource = await resourceDao.save(resource);
    } catch (error) {
      return left(DbFailure.unableToSave(error: error.toString()));
    }
    return right(resultResource);
  }

  Future<Either<DbFailure, List<Resource>>> returnListOfSingleResourceType(
      String resourceType) async {
    List<Resource> resultList;
    try {
      resultList =
          await resourceDao.getAllSortedById(resourceType: resourceType);
    } catch (error) {
      return left(DbFailure.unableToObtainList(error: error.toString()));
    }
    return right(resultList);
  }

  Future<Either<DbFailure, List<Resource>>> searchFunction(
      String resourceType, String searchString, String reference) async {
    List<Resource> resultList;
    try {
      resultList =
          await resourceDao.searchFor(resourceType, searchString, reference);
    } catch (error) {
      return left(DbFailure.unableToObtainList(error: error.toString()));
    }
    return right(resultList);
  }
}

I like this because in case there's an i/o error or something, it won't crash your app. Then, you can call this interface in your app like the following:

final patient = Patient(
    resourceType: 'Patient',
    name: [HumanName(text: 'New Patient Name')],
    birthDate: Date(DateTime.now()),
);

final saveResult = await IFhirDb().save(patient);

This will save your newly created patient to the locally embedded database.

IMPORTANT: this database will expect that all previously created resources have an id. When you save a resource, it will check to see if that resource type has already been stored. (Each resource type is saved in it's own store in the database). It will then check if there is an ID. If there's no ID, it will create a new one for that resource (along with metadata on version number and creation time). It will save it, and return the resource. If it already has an ID, it will copy the the old version of the resource into a _history store. It will then update the metadata of the new resource and save that version into the appropriate store for that resource. If, for instance, we have a previously created patient:

{
    "resourceType": "Patient",
    "id": "fhirfli-294057507-6811107",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2020-10-16T19:41:28.054369Z"
    },
    "name": [
        {
            "given": ["New"],
            "family": "Patient"
        }
    ],
    "birthDate": "2020-10-16"
}

And we update the last name to 'Provider'. The above version of the patient will be kept in _history, while in the 'Patient' store in the db, we will have the updated version:

{
    "resourceType": "Patient",
    "id": "fhirfli-294057507-6811107",
    "meta": {
        "versionId": "2",
        "lastUpdated": "2020-10-16T19:45:07.316698Z"
    },
    "name": [
        {
            "given": ["New"],
            "family": "Provider"
        }
    ],
    "birthDate": "2020-10-16"
}

This way we can keep track of all previous version of all resources (which is obviously important in medicine).

For most of the interactions (saving, deleting, etc), they work the way you'd expect. The only difference is search. Because Sembast is NoSQL, we can search on any of the fields in a resource. If in our interface class, we have the following function:

  Future<Either<DbFailure, List<Resource>>> searchFunction(
      String resourceType, String searchString, String reference) async {
    List<Resource> resultList;
    try {
      resultList =
          await resourceDao.searchFor(resourceType, searchString, reference);
    } catch (error) {
      return left(DbFailure.unableToObtainList(error: error.toString()));
    }
    return right(resultList);
  }

You can search for all immunizations of a certain patient:

searchFunction(
        'Immunization', 'patient.reference', 'Patient/$patientId');

This function will search through all entries in the 'Immunization' store. It will look at all 'patient.reference' fields, and return any that match 'Patient/$patientId'.

The last thing I'll mention is that this is a password protected db, using AES-256 encryption (although it can also use Salsa20). Anytime you use the db, you have the option of using a password for encryption/decryption. Remember, if you setup the database using encryption, you will only be able to access it using that same password. When you're ready to change the password, you will need to call the update password function. If we again assume we created a change password method in our interface, it might look something like this:

class IFhirDb {
  IFhirDb();
  final ResourceDao resourceDao = ResourceDao();
  ...
    Future<Either<DbFailure, Unit>> updatePassword(String oldPassword, String newPassword) async {
    try {
      await resourceDao.updatePw(oldPassword, newPassword);
    } catch (error) {
      return left(DbFailure.unableToUpdatePassword(error: error.toString()));
    }
    return right(Unit);
  }

You don't have to use a password, and in that case, it will save the db file as plain text. If you want to add a password later, it will encrypt it at that time.

General Store

After using this for a while in an app, I've realized that it needs to be able to store data apart from just FHIR resources, at least on occasion. For this, I've added a second class for all versions of the database called GeneralDao. This is similar to the ResourceDao, but fewer options. So, in order to save something, it would look like this:

await GeneralDao().save('password', {'new':'map'});
await GeneralDao().save('password', {'new':'map'}, 'key');

The difference between these two options is that the first one will generate a key for the map being stored, while the second will store the map using the key provided. Both will return the key after successfully storing the map.

Other functions available include:

// deletes everything in the general store
await GeneralDao().deleteAllGeneral('password'); 

// delete specific entry
await GeneralDao().delete('password','key'); 

// returns map with that key
await GeneralDao().find('password', 'key'); 

FHIR® is a registered trademark of Health Level Seven International (HL7) and its use does not constitute an endorsement of products by HL7®

Use this package as a library

Depend on it

Run this command:

With Flutter:

 $ flutter pub add fhir_db

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

dependencies:
  fhir_db: ^0.4.3

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

Import it

Now in your Dart code, you can use:

import 'package:fhir_db/dstu2.dart';
import 'package:fhir_db/dstu2/fhir_db.dart';
import 'package:fhir_db/dstu2/general_dao.dart';
import 'package:fhir_db/dstu2/resource_dao.dart';
import 'package:fhir_db/encrypt/aes.dart';
import 'package:fhir_db/encrypt/salsa.dart';
import 'package:fhir_db/r4.dart';
import 'package:fhir_db/r4/fhir_db.dart';
import 'package:fhir_db/r4/general_dao.dart';
import 'package:fhir_db/r4/resource_dao.dart';
import 'package:fhir_db/r5.dart';
import 'package:fhir_db/r5/fhir_db.dart';
import 'package:fhir_db/r5/general_dao.dart';
import 'package:fhir_db/r5/resource_dao.dart';
import 'package:fhir_db/stu3.dart';
import 'package:fhir_db/stu3/fhir_db.dart';
import 'package:fhir_db/stu3/general_dao.dart';
import 'package:fhir_db/stu3/resource_dao.dart'; 

example/lib/main.dart

import 'package:fhir/r4.dart';
import 'package:fhir_db/r4.dart';
import 'package:flutter/material.dart';
import 'package:test/test.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final resourceDao = ResourceDao();

  // await resourceDao.updatePw('newPw', null);
  await resourceDao.deleteAllResources(null);

  group('Playing with passwords', () {
    test('Playing with Passwords', () async {
      final patient = Patient(id: Id('1'));

      final saved = await resourceDao.save(null, patient);

      await resourceDao.updatePw(null, 'newPw');
      final search1 = await resourceDao.find('newPw',
          resourceType: R4ResourceType.Patient, id: Id('1'));
      expect(saved, search1[0]);

      await resourceDao.updatePw('newPw', 'newerPw');
      final search2 = await resourceDao.find('newerPw',
          resourceType: R4ResourceType.Patient, id: Id('1'));
      expect(saved, search2[0]);

      await resourceDao.updatePw('newerPw', null);
      final search3 = await resourceDao.find(null,
          resourceType: R4ResourceType.Patient, id: Id('1'));
      expect(saved, search3[0]);

      await resourceDao.deleteAllResources(null);
    });
  });

  final id = Id('12345');
  group('Saving Things:', () {
    test('Save Patient', () async {
      final humanName = HumanName(family: 'Atreides', given: ['Duke']);
      final patient = Patient(id: id, name: [humanName]);
      final saved = await resourceDao.save(null, patient);

      expect(saved.id, id);

      expect((saved as Patient).name?[0], humanName);
    });

    test('Save Organization', () async {
      final organization = Organization(id: id, name: 'FhirFli');
      final saved = await resourceDao.save(null, organization);

      expect(saved.id, id);

      expect((saved as Organization).name, 'FhirFli');
    });

    test('Save Observation1', () async {
      final observation1 = Observation(
        id: Id('obs1'),
        code: CodeableConcept(text: 'Observation #1'),
        effectiveDateTime: FhirDateTime(DateTime(1981, 09, 18)),
      );
      final saved = await resourceDao.save(null, observation1);

      expect(saved.id, Id('obs1'));

      expect((saved as Observation).code.text, 'Observation #1');
    });

    test('Save Observation1 Again', () async {
      final observation1 = Observation(
          id: Id('obs1'),
          code: CodeableConcept(text: 'Observation #1 - Updated'));
      final saved = await resourceDao.save(null, observation1);

      expect(saved.id, Id('obs1'));

      expect((saved as Observation).code.text, 'Observation #1 - Updated');

      expect(saved.meta?.versionId, Id('2'));
    });

    test('Save Observation2', () async {
      final observation2 = Observation(
        id: Id('obs2'),
        code: CodeableConcept(text: 'Observation #2'),
        effectiveDateTime: FhirDateTime(DateTime(1981, 09, 18)),
      );
      final saved = await resourceDao.save(null, observation2);

      expect(saved.id, Id('obs2'));

      expect((saved as Observation).code.text, 'Observation #2');
    });

    test('Save Observation3', () async {
      final observation3 = Observation(
        id: Id('obs3'),
        code: CodeableConcept(text: 'Observation #3'),
        effectiveDateTime: FhirDateTime(DateTime(1981, 09, 18)),
      );
      final saved = await resourceDao.save(null, observation3);

      expect(saved.id, Id('obs3'));

      expect((saved as Observation).code.text, 'Observation #3');
    });
  });

  group('Finding Things:', () {
    test('Find 1st Patient', () async {
      final search = await resourceDao.find(null,
          resourceType: R4ResourceType.Patient, id: id);
      final humanName = HumanName(family: 'Atreides', given: ['Duke']);

      expect(search.length, 1);

      expect((search[0] as Patient).name?[0], humanName);
    });

    test('Find 3rd Observation', () async {
      final search = await resourceDao.find(null,
          resourceType: R4ResourceType.Observation, id: Id('obs3'));

      expect(search.length, 1);

      expect(search[0].id, Id('obs3'));

      expect((search[0] as Observation).code.text, 'Observation #3');
    });

    test('Find All Observations', () async {
      final search = await resourceDao.getResourceType(
        null,
        resourceTypes: [R4ResourceType.Observation],
      );

      expect(search.length, 3);

      final idList = [];
      for (final obs in search) {
        idList.add(obs.id.toString());
      }

      expect(idList.contains('obs1'), true);

      expect(idList.contains('obs2'), true);

      expect(idList.contains('obs3'), true);
    });

    test('Find All (non-historical) Resources', () async {
      final search = await resourceDao.getAll(null);

      expect(search.length, 5);
      final patList = search.toList();
      final orgList = search.toList();
      final obsList = search.toList();
      patList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Patient);
      orgList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Organization);
      obsList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Observation);

      expect(patList.length, 1);

      expect(orgList.length, 1);

      expect(obsList.length, 3);
    });
  });

  group('Deleting Things:', () {
    test('Delete 2nd Observation', () async {
      await resourceDao.delete(
          null, null, R4ResourceType.Observation, Id('obs2'), null, null);

      final search = await resourceDao.getResourceType(
        null,
        resourceTypes: [R4ResourceType.Observation],
      );

      expect(search.length, 2);

      final idList = [];
      for (final obs in search) {
        idList.add(obs.id.toString());
      }

      expect(idList.contains('obs1'), true);

      expect(idList.contains('obs2'), false);

      expect(idList.contains('obs3'), true);
    });

    test('Delete All Observations', () async {
      await resourceDao.deleteSingleType(null,
          resourceType: R4ResourceType.Observation);

      final search = await resourceDao.getAll(null);

      expect(search.length, 2);

      final patList = search.toList();
      final orgList = search.toList();
      patList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Patient);
      orgList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Organization);

      expect(patList.length, 1);

      expect(patList.length, 1);
    });

    test('Delete All Resources', () async {
      await resourceDao.deleteAllResources(null);

      final search = await resourceDao.getAll(null);

      expect(search.length, 0);
    });
  });

  group('Password - Saving Things:', () {
    test('Save Patient', () async {
      await resourceDao.updatePw(null, 'newPw');
      final humanName = HumanName(family: 'Atreides', given: ['Duke']);
      final patient = Patient(id: id, name: [humanName]);
      final saved = await resourceDao.save('newPw', patient);

      expect(saved.id, id);

      expect((saved as Patient).name?[0], humanName);
    });

    test('Save Organization', () async {
      final organization = Organization(id: id, name: 'FhirFli');
      final saved = await resourceDao.save('newPw', organization);

      expect(saved.id, id);

      expect((saved as Organization).name, 'FhirFli');
    });

    test('Save Observation1', () async {
      final observation1 = Observation(
        id: Id('obs1'),
        code: CodeableConcept(text: 'Observation #1'),
        effectiveDateTime: FhirDateTime(DateTime(1981, 09, 18)),
      );
      final saved = await resourceDao.save('newPw', observation1);

      expect(saved.id, Id('obs1'));

      expect((saved as Observation).code.text, 'Observation #1');
    });

    test('Save Observation1 Again', () async {
      final observation1 = Observation(
          id: Id('obs1'),
          code: CodeableConcept(text: 'Observation #1 - Updated'));
      final saved = await resourceDao.save('newPw', observation1);

      expect(saved.id, Id('obs1'));

      expect((saved as Observation).code.text, 'Observation #1 - Updated');

      expect(saved.meta?.versionId, Id('2'));
    });

    test('Save Observation2', () async {
      final observation2 = Observation(
        id: Id('obs2'),
        code: CodeableConcept(text: 'Observation #2'),
        effectiveDateTime: FhirDateTime(DateTime(1981, 09, 18)),
      );
      final saved = await resourceDao.save('newPw', observation2);

      expect(saved.id, Id('obs2'));

      expect((saved as Observation).code.text, 'Observation #2');
    });

    test('Save Observation3', () async {
      final observation3 = Observation(
        id: Id('obs3'),
        code: CodeableConcept(text: 'Observation #3'),
        effectiveDateTime: FhirDateTime(DateTime(1981, 09, 18)),
      );
      final saved = await resourceDao.save('newPw', observation3);

      expect(saved.id, Id('obs3'));

      expect((saved as Observation).code.text, 'Observation #3');
    });
  });

  group('Password - Finding Things:', () {
    test('Find 1st Patient', () async {
      final search = await resourceDao.find('newPw',
          resourceType: R4ResourceType.Patient, id: id);
      final humanName = HumanName(family: 'Atreides', given: ['Duke']);

      expect(search.length, 1);

      expect((search[0] as Patient).name?[0], humanName);
    });

    test('Find 3rd Observation', () async {
      final search = await resourceDao.find('newPw',
          resourceType: R4ResourceType.Observation, id: Id('obs3'));

      expect(search.length, 1);

      expect(search[0].id, Id('obs3'));

      expect((search[0] as Observation).code.text, 'Observation #3');
    });

    test('Find All Observations', () async {
      final search = await resourceDao.getResourceType(
        'newPw',
        resourceTypes: [R4ResourceType.Observation],
      );

      expect(search.length, 3);

      final idList = [];
      for (final obs in search) {
        idList.add(obs.id.toString());
      }

      expect(idList.contains('obs1'), true);

      expect(idList.contains('obs2'), true);

      expect(idList.contains('obs3'), true);
    });

    test('Find All (non-historical) Resources', () async {
      final search = await resourceDao.getAll('newPw');

      expect(search.length, 5);
      final patList = search.toList();
      final orgList = search.toList();
      final obsList = search.toList();
      patList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Patient);
      orgList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Organization);
      obsList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Observation);

      expect(patList.length, 1);

      expect(orgList.length, 1);

      expect(obsList.length, 3);
    });
  });

  group('Password - Deleting Things:', () {
    test('Delete 2nd Observation', () async {
      await resourceDao.delete(
          'newPw', null, R4ResourceType.Observation, Id('obs2'), null, null);

      final search = await resourceDao.getResourceType(
        'newPw',
        resourceTypes: [R4ResourceType.Observation],
      );

      expect(search.length, 2);

      final idList = [];
      for (final obs in search) {
        idList.add(obs.id.toString());
      }

      expect(idList.contains('obs1'), true);

      expect(idList.contains('obs2'), false);

      expect(idList.contains('obs3'), true);
    });

    test('Delete All Observations', () async {
      await resourceDao.deleteSingleType('newPw',
          resourceType: R4ResourceType.Observation);

      final search = await resourceDao.getAll('newPw');

      expect(search.length, 2);

      final patList = search.toList();
      final orgList = search.toList();
      patList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Patient);
      orgList.retainWhere(
          (resource) => resource.resourceType == R4ResourceType.Organization);

      expect(patList.length, 1);

      expect(patList.length, 1);
    });

    test('Delete All Resources', () async {
      await resourceDao.deleteAllResources('newPw');

      final search = await resourceDao.getAll('newPw');

      expect(search.length, 0);

      await resourceDao.updatePw('newPw', null);
    });
  });
} 

Download Details:

Author: MayJuun

Source Code: https://github.com/MayJuun/fhir/tree/main/fhir_db

#sqflite  #dart  #flutter 

Garry Taylor

Garry Taylor

1669952228

Dijkstra's Algorithm Explained with Examples

In this tutorial, you'll learn: What is Dijkstra's Algorithm and how Dijkstra's algorithm works with the help of visual guides.

You can use algorithms in programming to solve specific problems through a set of precise instructions or procedures.

Dijkstra's algorithm is one of many graph algorithms you'll come across. It is used to find the shortest path from a fixed node to all other nodes in a graph.

There are different representations of Dijkstra's algorithm. You can either find the shortest path between two nodes, or the shortest path from a fixed node to the rest of the nodes in a graph.

In this article, you'll learn how Dijkstra's algorithm works with the help of visual guides.

How Does Dijkstra’s Algorithm Work?

Before we dive into more detailed visual examples, you need to understand how Dijkstra's algorithm works.

Although the theoretical explanation may seem a bit abstract, it'll help you understand the practical aspect better.

In a given graph containing different nodes, we are required to get the shortest path from a given node to the rest of the nodes.

These nodes can represent any object like the names of cities, letters, and so on.

Between each node is a number denoting the distance between two nodes, as you can see in the image below:

nodes-1

We usually work with two arrays – one for visited nodes, and another for unvisited nodes. You'll learn more about the arrays in the next section.

When a node is visited, the algorithm calculates how long it took to get to the node and stores the distance. If a shorter path to a node is found, the initial value assigned for the distance is updated.

Note that a node cannot be visited twice.

The algorithm runs recursively until all the nodes have been visited.

Dijkstra's Algorithm Example

In this section, we'll take a look at a practical example that shows how Dijkstra's algorithm works.

Here's the graph we'll be working with:

nodes

We'll use the table below to put down the visited nodes and their distance from the fixed node:

NODESHORTEST DISTANCE FROM FIXED NODE
A
B
C
D
E

Visited nodes = []
Unvisited nodes = [A,B,C,D,E]

Above, we have a table showing each node and the shortest distance from the that node to the fixed node. We are yet to choose the fixed node.

Note that the distance for each node in the table is currently denoted as infinity (∞). This is because we don't know the shortest distance yet.

We also have two arrays – visited and unvisited. Whenever a node is visited, it is added to the visited nodes array.

Let's get started!

To simplify things, I'll break the process down into iterations. You'll see what happens in each step with the aid of diagrams.

Iteration #1

The first iteration might seem confusing, but that's totally fine. Once we start repeating the process in each iteration, you'll have a clearer picture of how the algorithm works.

Step #1 - Pick an unvisited node

We'll choose A as the fixed node. So we'll find the shortest distance from A to every other node in the graph.

node1-1

We're going to give A a distance of 0 because it is the initial node. So the table would look like this:

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B
C
D
E

Step #2 - Find the distance from current nodenode1a-3

The next thing to do after choosing a node is to find the distance from it to the unvisited nodes around it.

The two unvisited nodes directly linked to A are B and C.

To get the distance from A to B:

0 + 4 = 4

0 being the value of the current node (A), and 4 being the distance between A and B in the graph.

To get the distance from A to C:

0 + 2 = 2

Step #3 - Update table with known distances

In the last step, we got 4 and 2 as the values of B and C respectively. So we'll update the table with those values:

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B4
C2
D
E

Step #4 - Update arrays

At this point, the first iteration is complete. We'll move node A to the visited nodes array:

Visited nodes = [A]
Unvisited nodes = [B,C,D,E]

Before we proceed to the next iteration, you should know the following:

  • Once a node has been visited, it cannot be linked to the current node. Refer to step #2 in the iteration above and step #2 in the next iteration.
  • A node cannot be visited twice.
  • You can only update the shortest known distance if you get a value smaller than the recorded distance.

Iteration #2

Step #1 - Pick an unvisited node

We have four unvisited nodes — [B,C,D,E]. So how do you know which node to pick for the next iteration?

Well, we pick the node with the smallest known distance recorded in the table. Here's the table:

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B4
C2
D
E

So we're going with node C.

node2-2

Step #2 - Find the distance from current node

To find the distance from the current node to the fixed node, we have to consider the nodes linked to the current node.

The nodes linked to the current node are A and B.

But A has been visited in the previous iteration so it will not be linked to the current node. That is:

node2a-1

From the diagram above,

  • The green color denotes the current node.
  • The blue color denotes the visited nodes. We cannot link to them or visit them again.
  • The red color shows the link from the unvisited nodes to the current node.

To find the distance from C to B:

2 + 1 = 3

2 above is recorded distance for node C while 1 is the distance between C and B in the graph.

Step #3 - Update table with known distances

In the last step, we got the value of B to be 3. In the first iteration, it was 4.

We're going to update the distance in the table to 3.

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B3
C2
D
E

So, A --> B = 4 (First iteration).

A --> C --> B = 3 (Second iteration).

The algorithm has helped us find the shortest path to B from A.

Step #4 - Update arrays

We're done with the last visited node. Let's add it to the visited nodes array:

Visited nodes = [A,C]
Unvisited nodes = [B,D,E]

Iteration #3

Step #1 - Pick an unvisited node

We're down to three unvisited nodes — [B,D,E]. From the array, B has the shortest known distance.

node3-2

To restate what is going on in the diagram above:

  • The green color denotes the current node.
  • The blue color denotes the visited nodes. We cannot link to them or visit them again.
  • The red color shows the link from the unvisited nodes to the current node.

Step #2 - Find the distance from current node

The nodes linked to the current node are D and E.

B (the current node) has a value of 3. Therefore,

For node D, 3 + 3 = 6.

For node E, 3 + 2 = 5.

Step #3 - Update table with known distances

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B3
C2
D6
E5

Step #4 - Update arrays

Visited nodes = [A,C,B]
Unvisited nodes = [D,E]

Iteration #4

Step #1 - Pick an unvisited node

Like other iterations, we'll go with the unvisited node with the shortest known distance. That is E.

node4-1

Step #2 - Find the distance from current node

According to our table, E has a value of 5.

For D in the current iteration,

5 + 5 = 10.

The value gotten for D here is 10, which is greater than the recorded value of 6 in the previous iteration. For this reason, we'll not update the table.

Step #3 - Update table with known distances

Our table remains the same:

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B3
C2
D6
E5

Step #4 - Update arrays

Visited nodes = [A,C,B,E]
Unvisited nodes = [D]

Iteration #5

Step #1 - Pick an unvisited node

We're currently left with one node in the unvisited array — D.

node5-1

Step #2 - Find the distance from current node

The algorithm has gotten to the last iteration. This is because all nodes linked to the current node have been visited already so we can't link to them.

Step #3 - Update table with known distances

Our table remains the same:

NODESHORTEST DISTANCE FROM FIXED NODE
A0
B3
C2
D6
E5

At this point, we have updated the table with the shortest distance from the fixed node to every other node in the graph.

Step #4 - Update arrays

Visited nodes = [A,C,B,E,D]
Unvisited nodes = []

As can be seen above, we have no nodes left to visit. Using Dijkstra's algorithm, we've found the shortest distance from the fixed node to others nodes in the graph.

Dijkstra's Algorithm Pseudocode Example

The pseudocode example in this section was gotten from Wikipedia. Here it is:

 1  function Dijkstra(Graph, source):
 2      
 3      for each vertex v in Graph.Vertices:
 4          dist[v] ← INFINITY
 5          prev[v] ← UNDEFINED
 6          add v to Q
 7      dist[source] ← 0
 8      
 9      while Q is not empty:
10          u ← vertex in Q with min dist[u]
11          remove u from Q
12          
13          for each neighbor v of u still in Q:
14              alt ← dist[u] + Graph.Edges(u, v)
15              if alt < dist[v]:
16                  dist[v] ← alt
17                  prev[v] ← u
18
19      return dist[], prev[]

Applications of Dijkstra's Algorithm

Here are some of the common applications of Dijkstra's algorithm:

  • In maps to get the shortest distance between locations. An example is Google Maps.
  • In telecommunications to determine transmission rate.
  • In robotic design to determine shortest path for automated robots.

Summary

In this article, we talked about Dijkstra's algorithm. It is used to find the shortest distance from a fixed node to all other nodes in a graph.

We started by giving a brief summary of how the algorithm works.

We then had a look at an example that further explained Dijkstra's algorithm in steps using visual guides.

We concluded with a pseudocode example and some of the applications of Dijkstra's algorithm.

Happy coding!

Original article source at https://www.freecodecamp.org

#algorithm #datastructures

Apipie: Rails API Documentation and Display tool using Ruby Syntax

API Documentation Tool

Apipie-rais is a DSL and Rails engine for documenting your RESTful API. Instead of traditional use of #comments, Apipie lets you describe the code, through the code. This brings advantages like:

  • No need to learn yet another syntax, you already know Ruby, right?
  • Possibility of reusing the docs for other purposes (such as validation)
  • Easier to extend and maintain (no string parsing involved)
  • Possibility of reusing other sources for documentation purposes (such as routes etc.)

The documentation is available from within your app (by default under the /apipie path.) In development mode, you can see the changes as you go. It's markup language agnostic, and even provides an API for reusing the documentation data in JSON.

Getting started

The easiest way to get Apipie up and running with your app is:

echo "gem 'apipie-rails'" >> Gemfile
bundle install
rails g apipie:install

Now you can start documenting your resources and actions (see DSL Reference for more info):

api :GET, '/users/:id'
param :id, :number, desc: 'id of the requested user'
def show
  # ...
end

Run your application and see the result at http://localhost:3000/apipie. For further processing, you can use http://localhost:3000/apipie.json.

For a more comprehensive getting started guide, see this demo, which includes features such as generating documentation from tests, recording examples etc.

Screenshots

https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-1.png

https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-2.png

Authors

Pajk and iNecas

Contributors

See Contributors page. Special thanks to all of them!

License

Apipie-rails is released under the MIT License

DSL Reference

Resource Description

You can describe a resource on the controller level. The description is introduced by calling resource_description do ... end.

Inheritance is supported, so you can specify common params for group of controllers in their parent class.

The following keywords are available (all are optional):

resource_id

How the resource will be referenced in Apipie (paths, see command etc.); by default controller_name.downcase is used.

name

Human readable name of resource. By default class.name.humanize is used.

short (also short_description)

Short description of the resource (it's shown on both the list of resources, and resource details)

desc (also description and full_description)

Full description of the resource (shown only in resource details)

param

Common params for all methods defined in controller/child controllers.

returns

Common responses for all methods defined in controller/child controllers.

api_base_url

What URL is the resource available under.

api_versions (also api_version)

What versions does the controller define the resource. (See Versioning for details.)

formats

Request / response formats.

error

Describe every possible error that can happen when calling all methods defined in controller. HTTP response code and description can be provided.

app_info

In case of versioning, this sets app info description on a per_version basis.

meta

Hash or array with custom metadata.

deprecated

Boolean value indicating if the resource is marked as deprecated. (Default false)

Example:

resource_description do
  short 'Site members'
  formats ['json']
  param :id, Fixnum, :desc => "User ID", :required => false
  param :resource_param, Hash, :desc => 'Param description for all methods' do
    param :ausername, String, :desc => "Username for login", :required => true
    param :apassword, String, :desc => "Password for login", :required => true
  end
  api_version "development"
  error 404, "Missing"
  error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
  error :unprocessable_entity, "Could not save the entity."
  returns :code => 403 do
     property :reason, String, :desc => "Why this was forbidden"
  end
  meta :author => {:name => 'John', :surname => 'Doe'}
  deprecated false
  description <<-EOS
    == Long description
     Example resource for rest api documentation
     These can now be accessed in <tt>shared/header</tt> with:
       Headline: <%= headline %>
       First name: <%= person.first_name %>

     If you need to find out whether a certain local variable has been
     assigned a value in a particular render call, you need to use the
     following pattern:

     <% if local_assigns.has_key? :headline %>
        Headline: <%= headline %>
     <% end %>

    Testing using <tt>defined? headline</tt> will not work. This is an
    implementation restriction.

    === Template caching

    By default, Rails will compile each template to a method in order
    to render it. When you alter a template, Rails will check the
    file's modification time and recompile it in development mode.
  EOS
end

Method Description

Then describe methods available to your API.

api

Describe how this method is exposed, and provide a short description. The first parameter is HTTP method (one of :GET/:POST/:PUT/:DELETE). The second parameter is the relative URL path which is mapped to this method. The last parameter is the methods short description. You can use this +api+ method more than once per method. It could be useful when there are more routes mapped to it.

When providing just one argument (description), or no argument at all, the paths will be loaded from the routes.rb file.

api!

Provide a short description and additional option. The last parameter is the methods short description. The paths will be loaded from routes.rb file. See Rails Routes Integration for more details.

api_versions (also api_version)

What version(s) does the action belong to. (See Versioning for details.)

param

Look at Parameter description section for details.

returns

Look at Response description section for details.

tags

Adds tags for grouping operations together in Swagger outputs. See swagger for more details. You can also provide tags in the Resource Description block so that they are automatically prepended to all action tags in the controller.

formats

Method level request / response formats.

error

Describe each possible error that can happen while calling this method. HTTP response code and description can be provided.

description

Full method description, which will be converted into HTML by the chosen markup language processor.

example

Provide an example of the server response; whole communication or response type. It will be formatted as code.

see

Provide reference to another method, this has to be a string with controller_name#method_name.

meta

Hash or array with custom metadata.

show

Resource is hidden from documentation when set to false (true by default)

Example:

# The simplest case: just load the paths from routes.rb
api!
def index
end

# More complex example
api :GET, "/users/:id", "Show user profile"
show false
error :code => 401, :desc => "Unauthorized"
error :code => 404, :desc => "Not Found", :meta => {:anything => "you can think of"}
param :session, String, :desc => "user is logged in", :required => true
param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
param :boolean_param, [true, false], :desc => "array validator with boolean"
param :proc_param, lambda { |val|
  val == "param value" ? true : "The only good value is 'param value'."
}, :desc => "proc validator"
param :param_with_metadata, String, :desc => "", :meta => [:your, :custom, :metadata]
returns :code => 200, :desc => "a successful response" do
   property :value1, String, :desc => "A string value"
   property :value2, Integer, :desc => "An integer value"
   property :value3, Hash, :desc => "An object" do
     property :enum1, ['v1', 'v2'], :desc => "One of 2 possible string values"
   end
end
tags %w[profiles logins]
tags 'more', 'related', 'resources'
description "method description"
formats ['json', 'jsonp', 'xml']
meta :message => "Some very important info"
example " 'user': {...} "
see "users#showme", "link description"
see :link => "users#update", :desc => "another link description"
def show
  #...
end

Parameter Description

Use param to describe every possible parameter. You can use the Hash validator in conjunction with a block given to the param method to describe nested parameters.

name

The first argument is the parameter name as a symbol.

validator

Second parameter is the parameter validator, choose one from section Validators

desc

Parameter description.

required

Set this true/false to make it required/optional. Default is optional

allow_nil

Setting this to true means that nil can be passed.

allow_blank

Like allow_nil, but for blank values. false, "", ' ', nil, [], and {} are all blank.

as

Used by the processing functionality to change the name of a key params.

meta

Hash or array with custom metadata.

show

Parameter is hidden from documentation when set to false (true by default)

missing_message

Specify the message to be returned if the parameter is missing as a string or Proc. Defaults to Missing parameter #{name} if not specified.

only_in

This can be set to :request or :response. Setting to :response causes the param to be ignored when used as part of a request description. Setting to :request causes this param to be ignored when used as part of a response description. If only_in is not specified, the param definition is used for both requests and responses. (Note that the keyword property is similar to param, but it has a :only_in => :response default).

Example:

param :user, Hash, :desc => "User info" do
  param :username, String, :desc => "Username for login", :required => true
  param :password, String, :desc => "Password for login", :required => true
  param :membership, ["standard","premium"], :desc => "User membership"
  param :admin_override, String, :desc => "Not shown in documentation", :show => false
  param :ip_address, String, :desc => "IP address", :required => true, :missing_message => lambda { I18n.t("ip_address.required") }
end
def create
  #...
end

DRY with param_group

Often, params occur together in more actions. Typically, most of the params for create and update actions are shared between them.

These params can be extracted with def_param_group and param_group keywords.

The definition is looked up in the scope of the controller. If the group is defined in a different controller, it might be referenced by specifying the second argument.

Example:

# v1/users_controller.rb
def_param_group :address do
  param :street, String
  param :number, Integer
  param :zip, String
end

def_param_group :user do
  param :user, Hash do
    param :name, String, "Name of the user"
    param_group :address
  end
end

api :POST, "/users", "Create a user"
param_group :user
def create
  # ...
end

api :PUT, "/users/:id", "Update a user"
param_group :user
def update
  # ...
end

# v2/users_controller.rb
api :POST, "/users", "Create a user"
param_group :user, V1::UsersController
def create
  # ...
end

Action Aware params

In CRUD operations, this pattern occurs quite often - params that need to be set are:

  • for create action: required => true and allow_nil => false
  • for update action: required => false and allow_nil => false

This makes it hard to share the param definitions across theses actions. Therefore, you can make the description a bit smarter by setting :action_aware => true.

You can specify explicitly how the param group should be evaluated with :as option (either :create or :update)

Example

def_param_group :user do
  param :user, Hash, :action_aware => true do
    param :name, String, :required => true
    param :description, String
  end
end

api :POST, "/users", "Create a user"
param_group :user
def create
  # ...
end

api :PUT, "/users/admin", "Create an admin"
param_group :user, :as => :create
def create_admin
  # ...
end

api :PUT, "/users/:id", "Update a user"
param_group :user
def update
  # ...
end

In this case, user[name] will be not be allowed nil for all actions and required only for create and create_admin. Params with allow_nil set explicitly don't have this value changed.

Action awareness is inherited from ancestors (in terms of nested params).

Response Description

The response from an API call can be documented by adding a returns statement to the method description. This is especially useful when using Apipie to auto-generate a machine-readable Swagger definition of your API (see the swagger section for more details).

A returns statement has several possible formats:

# format #1:  reference to a param-group
returns <param-group-name> [, :code => <number>|<http-response-code-symbol>] [, :desc => <human-readable description>]

# format #2:  inline response definition
returns :code => <number>|<http-response-code-symbol> [, :desc => <human-readable description>] do
    # property ...
    # property ...
    # param_group ...
end

# format #3:  describing an array-of-objects response
returns :array_of => <param-group-name> [, :code => <number>|<http-response-code-symbol>] [, :desc => <human-readable description>]

If the :code argument is ommitted, 200 is used.

Example

# ------------------------------------------------
# Example of format #1 (reference to param-group):
# ------------------------------------------------
# the param_group :pet is defined here to describe the output returned by the method below.
def_param_group :pet do
  property :pet_name, String, :desc => "Name of pet"
  property :animal_type, ['dog','cat','iguana','kangaroo'], :desc => "Type of pet"
end

api :GET, "/pets/:id", "Get a pet record"
returns :pet, :desc => "The pet"
def show_detailed
  render JSON({:pet_name => "Skippie", :animal_type => "kangaroo"})
end

# ------------------------------------------------
# Example of format #2 (inline):
# ------------------------------------------------
api :GET, "/pets/:id/with-extra-details", "Get a detailed pet record"
returns :code => 200, :desc => "Detailed info about the pet" do
  param_group :pet
  property :num_legs, Integer, :desc => "How many legs the pet has"
end
def show
  render JSON({:pet_name => "Barkie", :animal_type => "iguana", :legs => 4})
end

# ------------------------------------------------
# Example of format #3 (array response):
# ------------------------------------------------
api :GET, "/pets", "Get all pet records"
returns :array_of => :pet, :code => 200, :desc => "All pets"
def index
  render JSON([ {:pet_name => "Skippie", :animal_type => "kangaroo"},
                {:pet_name => "Woofie", :animal_type => "cat"} ])
end

Note the use of the property keyword rather than param. This is the preferred mechanism for documenting response-only fields.

The Property keyword

property is very similar to param with the following differences:

  • a property is :only_in => :response by default
  • a property is :required => :true by default
  • a property can be an :array_of objects

Example

property :example, :array_of => Hash do
  property :number1, Integer
  property :number2, Integer
end

Describing multiple return codes

To describe multiple possible return codes, the :returns keyword can be repeated as many times as necessary (once for each return code). Each one of the :returns entries can specify a different response format.

Example

api :GET, "/pets/:id/extra_info", "Get extra information about a pet"
  returns :desc => "Found a pet" do
    param_group :pet
    property 'pet_history', Hash do
      param_group :pet_history
    end
  end
  returns :code => :unprocessable_entity, :desc => "Fleas were discovered on the pet" do
    param_group :pet
    property :num_fleas, Integer, :desc => "Number of fleas on this pet"
  end
  def show_extra_info
    # ... implementation here
  end

Reusing a param_group to describe inputs and outputs

In many cases (such as CRUD implementations), the output from certain API calls is very similar - but not identical - to the inputs of the same or other API calls.

If you already have a :param_group that defines the input to a create or update routine, it would be quite frustrating to have to define a completely separate :param_group to describe the output of the show routine.

To address such situations, it is possible to define a single :param_group which combines param and property statements (as well as :only_in => :request / :only_in => :response) to differentiate between fields that are only expected in the request, only included in the response, or common to both.

This is somewhat analogous to the way Action Aware params work.

Example

 def_param_group :user_record
     param :name, String                                         # this is commong to both the request and the response
     param :force_update, [true, false], :only_in => :request    # this does not show up in responses
     property :last_login, String                                # this shows up only in the response
 end

api :POST, "/users", "Create a user"
param_group :user_record  # the :last_login field is not expected here, but :force_update is
def create
  # ...
end

api :GET, "/users", "Create a user"
returns :array_of => :user_record  # the :last_login field will be included in the response, but :force_update will not
def index
  # ...
end

Embedded response descriptions

If the code creating JSON responses is encapsulated within dedicated classes, it can be more convenient to place the response descriptions outside of the controller and embed them within the response generator.

To support such use cases, Apipie allows any class to provide a describe_own_properties class method which returns a description of the properties such a class would expose. It is then possible to specify that class in the returns statement instead of a param_group.

The describe_own_properties method is expected to return an array of Apipie::prop objects, each one describing a single property.

Example

class Pet
  # this method is automatically called by Apipie when Pet is specified as the returned object type
  def self.describe_own_properties
    [
        Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
        Apipie::prop(:animal_type, 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
        Apipie::additional_properties(false)  # this indicates that :pet_name and :animal_type are the only properties in the response
    ]
  end

  # this method w
  def json
    JSON({:pet_name => @name, :animal_type => @type })
  end
end


class PetsController
    api :GET, "/index", "Get all pets"
    returns :array_of => Pet  # Pet is a 'self-describing-class'
    def index
     # ...
    end
end

A use case where this is very useful is when JSON generation is done using a reflection mechanism or some other sort of declarative mechanism.

The Apipie::prop function expects the following inputs:

Apipie::prop(<property-name>, <property-type>, <options-hash> [, <array of sub-properties>])

# property-name should be a symbol
#
# property-type can be any of the following strings:
#   "integer": maps to a swagger "integer" with an "int32" format
#   "long": maps to a swagger "integer" with an "int64" format
#   "number": maps to a swagger "number"(no format specifier)
#   "float": maps to a swagger "number" with a "float" format
#   "double": maps to a swagger "number" with a "double" format
#   "string": maps to a swagger "string" (no format specifier)
#   "byte": maps to a swagger "string" with a "byte" format
#   "binary": maps to a swagger "string" with a "binary" format
#   "boolean": maps to a swagger "boolean" (no format specifier)
#   "date": maps to a swagger "string" with a "date" format
#   "dateTime": maps to a swagger "string" with a "date-time" format
#   "password": maps to a swagger "string" with a "password" format
#   "object": the property has sub-properties. include <array of sub-properties> in the call.
# (see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for more information
# about the mapped swagger types)
#
# options-hash can include any of the options fields allowed in a :returns statement.
# additionally, it can include the ':is_array => true', in which case the property is understood to be
# an array of the described type.

To describe an embedded object:

#
# PetWithMeasurements is a self-describing class with an embedded object
#
class PetWithMeasurements
  def self.describe_own_properties
    [
        Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
        Apipie::prop('animal_type', 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
        Apipie::prop(:pet_measurements, 'object', {}, [
            Apipie::prop(:weight, 'number', {:description => "Weight in pounds" }),
            Apipie::prop(:height, 'number', {:description => "Height in inches" }),
            Apipie::prop(:num_legs, 'number', {:description => "Number of legs", :required => false }),
            Apipie::additional_properties(false)
        ])
    ]
  end
end

#
# PetWithManyMeasurements is a self-describing class with an embedded array of objects
#
class PetWithManyMeasurements
  def self.describe_own_properties
    [
        Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
        Apipie::prop(:many_pet_measurements, 'object', {is_array: true}, [
            Apipie::prop(:weight, 'number', {:description => "Weight in pounds" }),
            Apipie::prop(:height, 'number', {:description => "Height in inches" }),
        ])
    ]
  end
end

Concerns

Sometimes, the actions are not defined in the controller class directly but included from a module instead. You can load the Apipie DSL into the module by extending it with Apipie::DSL::Concern.

The module can be used in more controllers. Therefore there is a way to substitute parts of the documentation in the module with controller specific values. These substitutions can be stated explicitly with apipie_concern_subst(:key => "value") (needs to be called before the module is included to take effect). The substitutions are performed in the paths and descriptions of APIs and names and descriptions of params.

There are some default substitutions available:

:controller_path

value of controller.controller_path, e.g. api/users for Api::UsersController. Only if not using the api! keyword.

:resource_id

Apipie identifier of the resource, e.g. users for Api::UsersController or set by resource_id

Example

# users_module.rb
module UsersModule
  extend Apipie::DSL::Concern

  api :GET, '/:controller_path', 'List :resource_id'
  def index
    # ...
  end

  api! 'Show a :resource'
  def show
    # ...
  end

  api :POST, '/:resource_id', "Create a :resource"
  param :concern, Hash, :required => true
    param :name, String, 'Name of a :resource'
    param :resource_type, ['standard','vip']
  end
  def create
    # ...
  end

  api :GET, '/:resource_id/:custom_subst'
  def custom
    # ...
  end
end

# users_controller.rb
class UsersController < ApplicationController

  resource_description { resource_id 'customers' }

  apipie_concern_subst(:custom_subst => 'custom', :resource => 'customer')
  include UsersModule

  # the following paths are documented
  # api :GET, '/users'
  # api :GET, '/customers/:id', 'Show a customer'
  # api :POST, '/customers', 'Create a customer'
  #   param :customer, :required => true do
  #     param :name, String, 'Name of a customer'
  #     param :customer_type, ['standard', 'vip']
  #   end
  # api :GET, '/customers/:custom'
end

Sometimes, it's needed to extend an existing controller method with additional parameters (usually when extending exiting API from plugins/rails engines). The concern can be also used for this purposed, using update_api method. The params defined in this block are merged with the params of the original method in the controller this concern is included to.

Example

module Concerns
  module OauthConcern
    extend Apipie::DSL::Concern

    update_api(:create, :update) do
      param :user, Hash do
        param :oauth, String, :desc => 'oauth param'
      end
    end
  end
end

The concern needs to be included to the controller after the methods are defined (either at the end of the class, or by using Controller.send(:include, Concerns::OauthConcern).

Response validation

The swagger definitions created by Apipie can be used to auto-generate clients that access the described APIs. Those clients will break if the responses returned from the API do not match the declarations. As such, it is very important to include unit tests that validate the actual responses against the swagger definitions.

The implemented mechanism provides two ways to include such validations in RSpec unit tests: manual (using an RSpec matcher) and automated (by injecting a test into the http operations 'get', 'post', raising an error if there is no match).

Example of the manual mechanism:

require 'apipie/rspec/response_validation_helper'

RSpec.describe MyController, :type => :controller, :show_in_doc => true do

  describe "GET stuff with response validation" do
    render_views   # this makes sure the 'get' operation will actually
                   # return the rendered view even though this is a Controller spec

    it "does something" do
      response = get :index, {format: :json}

      # the following expectation will fail if the returned object
      # does not match the 'returns' declaration in the Controller,
      # or if there is no 'returns' declaration for the returned
      # HTTP status code
      expect(response).to match_declared_responses
    end
  end
end

Example of the automated mechanism:

require 'apipie/rspec/response_validation_helper'

RSpec.describe MyController, :type => :controller, :show_in_doc => true do

  describe "GET stuff with response validation" do
    render_views
    auto_validate_rendered_views

    it "does something" do
      get :index, {format: :json}
    end
    it "does something else" do
      get :another_index, {format: :json}
    end
  end

  describe "GET stuff without response validation" do
    it "does something" do
      get :index, {format: :json}
    end
    it "does something else" do
      get :another_index, {format: :json}
    end
  end
end

Configuration Reference

Create a configuration file in e.g. /config/initializers/apipie.rb. You can set the application name, footer text, API and documentation base URL and turn off validations. You can also choose your favorite markup language for full descriptions.

app_name

Name of your application; used in breadcrumbs navigation.

copyright

Copyright information (shown in page footer).

compress_examples

If true recorded examples are compressed using Zlib. Useful for big test-suits.

doc_base_url

Documentation frontend base url.

api_base_url

Base url for default version of your API. To set it for specific version use config.api_base_url[version] = url.

default_version

Default API version to be used (1.0 by default)

validate

Parameters validation is turned off when set to false. When set to :explicitly, you must invoke parameter validation yourself by calling controller method apipie_validations (typically in a before_action). When set to :implicitly (or just true), your controller's action methods are wrapped with generated methods which call apipie_validations, and then call the action method. (:implicitly by default)

validate_value

Check the value of params against specified validators (true by default)

validate_presence

Check the params presence against the documentation.

validate_key

Check the received params to ensure they are defined in the API. (false by default)

action_on_non_validated_keys

Either :raise or :skip. If validate_key fails, raise error or delete the non-validated key from the params and log the key (:raise by default)

process_params

Process and extract the parameter defined from the params of the request to the api_params variable

app_info

Application long description.

reload_controllers

Set to enable/disable reloading controllers (and the documentation with it). Enabled by default in development.

api_controllers_matcher

For reloading to work properly you need to specify where your API controllers are. Can be an array if multiple paths are needed

api_routes

Set if your application uses a custom API router, different from the Rails default

routes_formatter

An object providing the translation from the Rails routes to the format usable in the documentation when using the api! keyword. By default, the Apipie::RoutesFormatter is used.

markup

You can choose markup language for descriptions of your application, resources and methods. RDoc is the default but you can choose from Apipie::Markup::Markdown.new or Apipie::Markup::Textile.new. In order to use Markdown you need Maruku gem and for Textile you need RedCloth. Add those to your gemfile and run bundle if you want to use them. You can also add any other markup language processor.

layout

Name of a layout template to use instead of Apipie's layout. You can use Apipie.include_stylesheets and Apipie.include_javascripts helpers to include Apipie's stylesheets and javascripts.

ignored

An array of controller names (strings) (might include actions as well) to be ignored when generationg the documentation e.g. %w[Api::CommentsController Api::PostsController#post]

namespaced_resources

Use controller paths instead of controller names as resource id. This prevents same named controllers overwriting each other.

authenticate

Pass a proc in order to authenticate user. Pass nil for no authentication (by default).

authorize

Pass a proc in order to authorize controllers and methods. The Proc is evaluated in the controller context.

show_all_examples

Set this to true to set show_in_doc=1 in all recorded examples

ignore_allow_blank_false

allow_blank: false was incorrectly ignored up until version 0.6.0, this bug was fixed in 0.7.0 if you need the old behavior, set this to true

link_extension

The extension to use for API pages ('.html' by default). Link extensions in static API docs cannot be changed from '.html'.

languages

List of languages the API documentation should be translated into. Empty by default.

default_locale

Locale used for generating documentation when no specific locale is set. Set to 'en' by default.

locale

Pass locale setter/getter

config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }

translate

Pass proc to translate strings using the localization library your project uses. For example see Localization

Example:

Apipie.configure do |config|
  config.app_name = "Test app"
  config.copyright = "&copy; 2012 Pavel Pokorny"
  config.doc_base_url = "/apidoc"
  config.api_base_url = "/api"
  config.validate = false
  config.markup = Apipie::Markup::Markdown.new
  config.reload_controllers = Rails.env.development?
  config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
  config.api_routes = Rails.application.routes
  config.app_info["1.0"] = "
    This is where you can inform user about your application and API
    in general.
  "
  config.authenticate = Proc.new do
     authenticate_or_request_with_http_basic do |username, password|
       username == "test" && password == "supersecretpassword"
    end
  end
  config.authorize = Proc.new do |controller, method, doc|
    !method   # show all controller doc, but no method docs.
  end
end

checksum_path

Used in ChecksumInHeaders middleware (see JSON checksums for more info). It contains path prefix(es) where the header with checksum is added. If set to nil, checksum is added in headers in every response. e.g. %w[/api /apipie]

update_checksum

If set to true, the checksum is recalculated with every documentation_reload call

Rails Routes Integration

Apipie is able to load the information about the paths based on the routes defined in the Rails application, by using the api! keyword in the DSL.

It should be usable out of box, however, one might want to do some customization (such as omitting some implicit parameters in the path etc.). For this kind of customizations one can create a new formatter and pass as the Apipie.configuration.routes_formatter option, like this:

class MyFormatter < Apipie::RoutesFormatter
  def format_path(route)
    super.gsub(/\(.*?\)/, '').gsub('//','') # hide all implicit parameters
  end
end

Apipie.configure do |config|
 ...
 config.routes_formatter = MyFormatter.new
 ...
end

A similar way can be used to influence things like order, or a description of the loaded APIs, even omitting some paths if needed.

Processing

The goal is to extract and pre-process parameters of the request.

For example Rails, by default, transforms an empty array to nil value. Perhaps you want to transform it again into an empty array. Or you want to support an enumeration type (comma separated values) and you want to automatically transform this string into an array.

To use it, set the process_params configuration variable to true.

Also by using as you can separate your API parameter names from the names you are using inside your code.

To implement it, you just have to write a process_value function in your validator:

For an enumeration type:

def process_value(value)
 value ? value.split(',') : []
end

Validators

Every parameter needs to have an associated validator. For now there are some basic validators. You can always provide your own to achieve complex results.

If validations are enabled (default state) the parameters of every request are validated. If the value is wrong an +ArgumentError+ exception is raised and can be rescued and processed. It contains a description of the parameter value expectations. Validations can be turned off in the configuration file.

Parameter validation normally happens after before_actions, just before your controller method is invoked. If you prefer to control when parameter validation occurs, set the configuration parameter validate to :explicitly. You must then call the apipie_validations method yourself, e.g.:

before_action :apipie_validations

This is useful if you have before_actions which use parameter values: just add them after the apipie_validations before_action.

TypeValidator

Check the parameter type. Only String, Hash and Array are supported for the sake of simplicity. Read more to find out how to add your own validator.

param :session, String, :desc => "user is logged in", :required => true
param :facts, Hash, :desc => "Additional optional facts about the user"

RegexpValidator

Check parameter value against given regular expression.

param :regexp_param, /^[0-9]* years/, :desc => "regexp param"

EnumValidator

Check if parameter value is included in the given array.

param :enum_param, [100, "one", "two", 1, 2], :desc => "enum validator"

ProcValidator

If you need more complex validation and you know you won't reuse it, you can use the Proc/lambda validator. Provide your own Proc, taking the value of the parameter as the only argument. Return true if value passes validation or return some text about what is wrong otherwise. _Don't use the keyword return if you provide an instance of Proc (with lambda it is ok), just use the last statement return property of ruby.

param :proc_param, lambda { |val|
  val == "param value" ? true : "The only good value is 'param value'."
}, :desc => "proc validator"

HashValidator

You can describe hash parameters in depth if you provide a block with a description of nested values.

param :user, Hash, :desc => "User info" do
  param :username, String, :desc => "Username for login", :required => true
  param :password, String, :desc => "Password for login", :required => true
  param :membership, ["standard","premium"], :desc => "User membership"
end

NilValidator

In fact there isn't any NilValidator, but setting it to nil can be used to override parameters described on the resource level.

param :user, nil
def destroy
  #...
end

NumberValidator

Check if the parameter is a positive integer number or zero

param :product_id, :number, :desc => "Identifier of the product", :required => true
param :quantity, :number, :desc => "Number of products to order", :required => true

DecimalValidator

Check if the parameter is a decimal number

param :latitude, :decimal, :desc => "Geographic latitude", :required => true
param :longitude, :decimal, :desc => "Geographic longitude", :required => true

ArrayValidator

Check if the parameter is an array

Additional options

of

Specify the type of items. If not given it accepts an array of any item type

in

Specify an array of valid item values.

Examples

Assert things is an array of any items

param :things, Array

Assert hits must be an array of integer values

param :hits, Array, of: Integer

Assert colors must be an array of valid string values

param :colors, Array, in: ["red", "green", "blue"]

The retrieving of valid items can be deferred until needed using a lambda. It is evaluated only once

param :colors, Array, in: ->  { Color.all.pluck(:name) }

NestedValidator

You can describe nested parameters in depth if you provide a block with a description of nested values.

param :comments, Array, :desc => "User comments" do
  param :name, String, :desc => "Name of the comment", :required => true
  param :comment, String, :desc => "Full comment", :required => true
end

Adding custom validator

Only basic validators are included but it is really easy to add your own. Create a new initializer with a subclass of Apipie::Validator::BaseValidator. Two methods are required to implement this - instance method validate(value) and class method build(param_description, argument, options, block).

When searching for the validator +build+ method, every subclass of Apipie::Validator::BaseValidator is called. The first one that returns the constructed validator object is used.

Example: Adding IntegerValidator

We want to check if the parameter value is an integer like this:

param :id, Integer, :desc => "Company ID"

So we create apipie_validators.rb initializer with this content:

class IntegerValidator < Apipie::Validator::BaseValidator

  def initialize(param_description, argument)
    super(param_description)
    @type = argument
  end

  def validate(value)
    return false if value.nil?
    !!(value.to_s =~ /^[-+]?[0-9]+$/)
  end

  def self.build(param_description, argument, options, block)
    if argument == Integer || argument == Fixnum
      self.new(param_description, argument)
    end
  end

  def description
    "Must be #{@type}."
  end
end

Parameters of the build method:

param_description

Instance of Apipie::ParamDescription contains all given information about the validated parameter.

argument

Specified validator; in our example it is +Integer+

options

Hash with specified options, for us just {:desc => "Company ID"}

block

Block converted into Proc, use it as you desire. In this example nil.

If your validator includes valid values that respond true to .blank?, you should also define:

def ignore_allow_blank?  true end

so that the validation does not fail for valid values.

Versioning

Every resource/method can belong to one or more versions. The version is specified with the api_version DSL keyword. When not specified, the resource belongs to config.default_version ("1.0" by default)

resource_description do
  api_versions "1", "2"
end

api :GET, "/api/users/", "List: users"
api_version "1"
def index
  # ...
end

api :GET, "/api/users/", "List: users", :deprecated => true

In the example above we say the whole controller/resource is defined for versions "1" and "2", but we override this by explicitly saying index belongs only to version "1". Also, inheritance works (therefore we can specify the api_version for the parent controller, and all children will know about that). Routes can be flagged as deprecated, and an annotation will be added to them when viewing in the API documentation.

From the Apipie API perspective, the resources belong to the version. With versioning, there are paths like this provided by apipie:

/apipie/1/users/index
/apipie/2/users/index

When not specifying the version explicitly in the path (or in DSL), default version (Apipie.configuration.default_version) is used instead ("1.0" by default). Therefore, an application that doesn't need versioning should work as before.

The static page generator takes a version parameter (or uses default).

You can specify the versions for the examples, with the versions keyword. It specifies the versions the example is used for. When not specified, it's shown in all versions with the given method.

When referencing or quering the resource/method descripion, this format should be used: "version#resource#method". When not specified, the default version is used instead.

Markup

The default markup language is RDoc. It can be changed in the config file (config.markup=) to one of these:

Markdown

Use Apipie::Markup::Markdown.new. You need Maruku gem.

Textile

Use Apipie::Markup::Textile.new. You need RedCloth gem.

Or provide you own object with a to_html(text) method. For inspiration, this is how Textile markup usage is implemented:

class Textile
  def initialize
    require 'RedCloth'
  end
  def to_html(text)
    RedCloth.new(text).to_html
  end
end

Localization

Apipie has support for localized API documentation in both formats (JSON and HTML). Apipie uses the library I18n for localization of itself. Check config/locales directory for available translations.

A major part of strings in the documentation comes from the API. As preferences regarding localization libraries differ amongst project, Apipie needs to know how to set the locale for your project, and how to translate a string using the library your project uses. That can be done using lambdas in configuration.

Sample configuration when your project uses FastGettext

Apipie.configure do |config|
 ...
 config.languages = ['en', 'cs']
 config.default_locale = 'en'
 config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }
 config.translate = lambda do |str, loc|
   old_loc = FastGettext.locale
   FastGettext.set_locale(loc)
   trans = _(str)
   FastGettext.set_locale(old_loc)
   trans
 end
end

And the strings in the API documentation need to be marked with the N_() function

api :GET, "/users/:id", N_("Show user profile")
param :session, String, :desc => N_("user is logged in"), :required => true

When your project use I18n, localization related configuration could appear as follows

Apipie.configure do |config|
 ...
 config.languages = ['en', 'cs']
 config.default_locale = 'en'
 config.locale = lambda { |loc| loc ? I18n.locale = loc : I18n.locale }
 config.translate = lambda do |str, loc|
   return '' if str.blank?
   I18n.t str, locale: loc, scope: 'doc'
 end
end

And the strings in the API documentation needs to be in the form of translation keys

api :GET, "/users/:id", "show_user_profile"
param :session, String, :desc => "user_is_logged_in", :required => true

The localized versions of the documentation are distinguished by language in the filename. E.g. doc/apidoc/apidoc.cs.html is static documentation in the Czech language. If the language is missing, e.g. doc/apidoc/apidoc.html, the documentation is localized with the default_locale.

The dynamic documentation follows the same schema. The http://localhost:3000/apidoc/v1.cs.html is documentation for version '1' of the API in the Czech language. For JSON descriptions, the API applies the same format: http://localhost:3000/apidoc/v1.cs.json

Modifying Views

To modify the views of your documentation, run rails g apipie:views. This will copy the Apipie views to app/views/apipie/apipies and app/views/layouts/apipie.

Static files

To generate a static version of documentation (perhaps to put it on your project site or something), run the rake apipie:static task. It will create a set of HTML files (multi-pages, single-page, plain) in your doc directory. If you prefer a JSON version run rake apipie:static_json. By default the documentation for the default API version is used. You can specify the version with rake apipie:static[2.0]

When you want to avoid any unnecessary computation in production mode, you can generate a cache with rake apipie:cache and configure the app to use it in production with config.use_cache = Rails.env.production?

Default cache dir is File.join(Rails.root, "public", "apipie-cache"), you can change it to where you want, example: config.cache_dir = File.join(Rails.root, "doc", "apidoc").

If, for some complex cases, you need to generate/re-generate just part of the cache use rake apipie:cache cache_part=index resp. rake apipie:cache cache_part=resources To generate it for different locations for further processing use rake apipie:cache OUT=/tmp/apipie_cache.

Static Swagger (OpenAPI 2.0) files

To generate a static Swagger definition file from the api, run rake apipie:static_swagger_json. By default the documentation for the default API version is used. You can specify the version with rake apipie:static_swagger_json[2.0]. A swagger file will be generated for each locale. The files will be generated in the same location as the static_json files, but instead of being named schema_apipie[.locale].json, they will be called schema_swagger[.locale].json.

Specifying default values for parameters

Swagger allows method definitions to include an indication of the the default value for each parameter. To include such indications, use :default_value => <some value> in the parameter definition DSL. For example:

param :do_something, Boolean, :desc => "take an action", :required => false, :default_value => false

Generated Warnings

The help identify potential improvements to your documentation, the swagger generation process issues warnings if it identifies various shortcomings of the DSL documentation. Each warning has a code to allow selective suppression (see swagger-specific configuration below)

100:missing short description for method
101:added missing / at beginning of path
102:no return codes specified for method
103:a parameter is a generic Hash without an internal type specification
104:a parameter is an 'in-path' parameter, but specified as 'not required' in the DSL
105:a parameter is optional but does not have a default value specified
106:a parameter was ommitted from the swagger output because it is a Hash without fields in a formData specification
107:a path parameter is not described
108:inferring that a parameter type is boolean because described as an enum with [false,true] values

Swagger-Specific Configuration Parameters

There are several configuration parameters that determine the structure of the generated swagger file:

config.swagger_content_type_input

If the value is :form_data - the swagger file will indicate that the server consumes the content types application/x-www-form-urlencoded and multipart/form-data. Non-path parameters will have the value "in": "formData". Note that parameters of type Hash that do not have any fields in them will be ommitted from the resulting files, as there is no way to describe them in swagger.

If the value is :json - the swagger file will indicate that the server consumes the content type application/json. All non-path parameters will be included in the schema of a single "in": "body" parameter of type object.

You can specify the value of this configuration parameter as an additional input to the rake command (e.g., rake apipie:static_swagger_json[2.0,form_data]).

config.swagger_json_input_uses_refs

This parameter is only relevant if swagger_content_type_input is :json.

If true: the schema of the "in": "body" parameter of each method is given its own entry in the definitions section, and is referenced using $ref from the method definition.

If false: the body parameter definitions are inlined within the method definitions.

config.swagger_include_warning_tags

If true: in addition to tagging methods with the name of the resource they belong to, methods for which warnings have been issued will be tagged with.

config.swagger_suppress_warnings

If false: no warnings will be suppressed

If true: all warnings will be suppressed

If an array of values (e.g., [100,102,107]), only the warnings identified by the numbers in the array will be suppressed.

config.swagger_api_host

The value to place in the swagger host field.

Default is localhost:3000

If nil then then host field will not be included.

config.swagger_allow_additional_properties_in_response

If false (default): response descriptions in the generated swagger will include an additional-properties: false field

If true: the additional-properties: false field will not be included in response object descriptions

config.swagger_schemes

An array of transport schemes that the API supports. This can include any combination of http, https, ws and wss. By default to encourage good security practices, ['https'] is specified.

config:swagger_security_definitions

If the API requires authentication, you can specify details of the authentication mechanisms supported as a (Hash) value here. See [https://swagger.io/docs/specification/2-0/authentication/] for details of what values can be specified By default, no security is defined.

config.swagger_global_security

If the API requires authentication, you can specify which of the authentication mechanisms are supported by all API operations as an Array of hashes here. This should be used in conjunction with the mechanisms defined by swagger_security_definitions. See [https://swagger.io/docs/specification/2-0/authentication/] for details of what values can be specified By default, no security is defined.

Known limitations of the current implementation

  • There is currently no way to document the structure and content-type of the data returned from a method
  • Recorded examples are currently not included in the generated swagger file
  • The apipie formats value is ignored.
  • It is not possible to specify the "consumed" content type on a per-method basis
  • It is not possible to leverage all of the parameter type/format capabilities of swagger
  • Only OpenAPI 2.0 is supported
  • Responses are defined inline and not as a $ref
  • It is not possible to specify per-operation security requirements (only global)

Dynamic Swagger generation

To generate swagger dynamically, use http://localhost:3000/apipie.json?type=swagger.

Note that authorization is not supported for dynamic swagger generation, so if config.authorize is defined, dynamic swagger generation will be disabled.

Dynamically generated swagger is not cached, and is always generated on the fly.

JSON checksums

If the API client needs to be sure that the JSON didn't changed, add the ApipieChecksumInHeaders middleware in your rails app. It can add a checksum of the entire JSON document in the response headers.

"Apipie-Checksum"=>"fb81460e7f4e78d059f826624bdf9504"

Apipie bindings uses this feature to refresh its JSON cache.

To set it up add the following to your application.rb

require 'apipie/middleware/checksum_in_headers'
# Add JSON checksum in headers for smarter caching
config.middleware.use "Apipie::Middleware::ChecksumInHeaders"

And in your apipie initializer allow checksum calculation

Apipie.configuration.update_checksum = true

By default the header is added to responses for config.doc_base_url and /api. It can be changed in configuration (see Configuration Reference for details).

The checksum calculation is lazy, and done with the first request. If you run with use_cache = true, do not forget to run the rake task apipie:cache.

Tests Integration

Apipie integrates with automated testing in two ways. Documentation bootstrapping and examples recording.

Documentation Bootstrapping

Let's say you have an application without REST API documentation. However you have a set of tests that are run against this API. A lot of information is already included in these tests, it just needs to be extracted somehow. Luckily, Apipie provides such a feature.

When running the tests, set the APIPIE_RECORD=params environment variable or call Apipie.record('params') from specs starter. You can either use it with functional tests:

APIPIE_RECORD=params rake test:functionals

or you can run your server with this param, in case you run the tests against running server:

APIPIE_RECORD=params rails server

When the process quits, the data from requests/responses are used to determine the documentation. It's quite raw, but it makes the initial phase much easier.

Examples Recording

You can also use the tests to generate up-to-date examples for your code. Similar to the bootstrapping process, you can use it with functional tests or a running server, setting APIPIE_RECORD=examples or calling Apipie.record('examples') in your specs starter.

APIPIE_RECORD=examples rake test:functionals
APIPIE_RECORD=examples rails server

The data is written into doc/apipie_examples.yml. By default, only the first example is shown for each action. You can customize this by setting the show_in_doc attribute at each example.

You can add a title to the examples (useful when showing more than one example per method) by adding a 'title' attribute.

--- !omap
  - announcements#index:
    - !omap
      - title: This is a custom title for this example
      - verb: :GET
      - path: /api/blabla/1
      - versions:
        - '1.0'
      - query:
      - request_data:
      - response_data:
        ...
      - code: 200
      - show_in_doc: 1   # If 1, show. If 0, do not show.
      - recorded: true

In RSpec you can add metadata to examples. We can use that feature to mark selected examples - the ones that perform the requests that we want to show as examples in the documentation.

For example, we can add show_in_doc to examples, like this:

describe "This is the correct path" do
  it "some test", :show_in_doc do
    ....
  end
end

context "These are edge cases" do
  it "Can't authenticate" do
    ....
  end

   it "record not found" do
     ....
   end
end

And then configure RSpec in this way:

RSpec.configure do |config|
  config.treat_symbols_as_metadata_keys_with_true_values = true
  config.filter_run :show_in_doc => true if ENV['APIPIE_RECORD']
end

This way, when running in recording mode, only the tests that have been marked with the :show_in_doc metadata will be run, and hence only those will be used as examples.

Caveats

Make sure to enable config.render_views in your config/rails_helper.rb or config/spec_helper.rb if you're using jbuilder, or you will get back empty results

Bindings Generator

In earlier versions (<= 0.0.13), there was a simple client generator as a part of Apipie gem. As more features and users came to Apipie, there was a greater need for changes on a per project basis. It's hard (or even impossible) to provide a generic solution for the client code. We also don't want to tell you what's the right way to do it (what gems to use, how the API should look like etc.).

Therefore you can't generate client code directly by a rake task in further versions.

There is, however, an even better and more flexible way to reuse your API documentation for this purpose: using the API the Apipie provides in the generator code. Check out our sister project apipie-bindings, as they use exactly this approach. You also don't need to run the service, provided it uses Apipie as a backend.

And if you write one on your own, don't hesitate to share it with us!

Contributing

Since this gem does not have a Gemfile, you need to specify it in your shell with:

Then, you can install dependencies and run the test suite:

Disqus Integration

You can setup Disqus discussion within your documentation. Just set the credentials in the Apipie configuration:

config.disqus_shortname = "MyProjectDoc"

External References


Author: Apipie
Source code: https://github.com/Apipie/apipie-rails
License: Apache-2.0, MIT licenses found


#ruby   #ruby-on-rails 

Orpha  Leannon

Orpha Leannon

1617765879

Comprehensive Guide to Modules in Ruby 3

Ruby modules can appear to be very similar to Ruby classes. After going through this you’ll be able to:

  • Understand the difference between Classes and Modules in Ruby
  • Build out Ruby modules
  • Work with nested modules
  • Combine Classes and Modules
  • See how modules can be used in large-scale, production Rails applications

Source code:

https://github.com/jordanhudgens/ruby-3/blob/master/ruby_modules.rb

#ruby #ruby-on-rails