image0

swagccg_m2m

MatLab only client code generator for swagger (OpenAPI 2.0). Using MatLab. For MatLab

Summary

Immediately testing new resources is important if resources are going to be co-dependent. While the tools at SwaggerHub are mind blowing they may represent an overkill for not yet production code. Typing a single query can be done in any browser or with tools like curl. This tool aims to place itself between those two extreme categories.

Installation

1. Download the User Distribution

Releases are published on GitHub and mirrored on the file-exchange. If you have trouble related to newline try a git clone.

I. Download the user distribution from GitHub https://github.com/erkandem/swagccg-m2m/releases/latest

  1. Unzip it
  2. Run the swagccg_m2m_setup. It will put static files like the template, the creation script and a zip file with client dependencies in location of your choice and add them to search path.

2. MPM

🚨 not yet

mpm install swagccg-m2m

Simple MATLAB package management inspired by pip

3. git clone

  1. Clone it.
git clone https://github.com/erkandem/swagccg-m2m.git tmpdir
  1. create a user distribution swagccg_m2m_package
  2. change to ../packages
  3. follow the steps 1.II

The git clone way is rather for developers of this repo. Nonetheless, running swagccg_m2m_package after cloning will package a user version. Currently, all dependencies are included in a .zip file.

Getting Started

Client Code Generation

Let’s start with the usual.

mkdir('playground');
cd('playground');

The swagccg_m2m assumes that a confi.json file is in your working directory. Below is an example of such a JSON-file. Create this file yourself or copy it from this location:

confi_path = fullfile(fileparts(which('swagccg_m2m__init__')), 'examples', 'example_confi.json' );

confi.json

The swagger_path key accepts a file path or web URL

{
  "swagger_path": "https://petstore.swagger.io/v2/swagger.json",
  "target_path": "PetStoreClient.m",
  "class_name": "PetStoreClient",

  "api_port_local": "5000",
  "api_url_base_local": "127.0.0.1",
  "api_protocol_local": "http",

  "api_port_remote": "80",
  "api_url_base_remote": "petstore.swagger.io",
  "api_protocol_remote": "https"
}

You can now call the code generator with:

swagccg_m2m;

Or pass the path string.

swagccg_m2m(confi_path);

So now check whether you got your client in your working directory.

🎉🎉🎈🎉

Client Code Usage

Take a look at the test and click your way through section by section. Meanwhile you could use the Swagger User Interface in parallel https://petstore.swagger.io to test the test.

playbook_location = fullfile(fileparts(which('swagccg_m2m__init__')), 'tests', 'test_petstore_play_book.m');
copyfile(playbook_location, 'test_template.m');
edit test_template

a Word on JSON in MatLab

MatLab has a built-in function to encode and decode JSON objects to MatLab types. Thepaths object within a swagger.json API definition has characters like / or curly braces in case of path parameters like /{pathParam}. Obviously strings with these characters are not valid variables or fieldnames in MatLab. Therefore a version of loadjson from jsonlab was modified to overcome that hurdle.

Finally

🚨 the tool is not designed to work out of the box for your project

It’s not that I don’t believe in miracles. But I’d expect that you will need to work on the client code after generating the client code. Specifically, everything around Authentication. This is because most of the swagger details are not parsed.

gotchas

  • authorization is likely to be a break-point
  • most of the swagger details are not parsed
  • data models and mapping is omitted but adaptable
  • little to none HTTP status codes parsing
  • assumes some knowledge on HTTP HEADER, BODY, METHODs

Further Reading

Project Documentation

Mark Masse, REST API Design Rulebook - Designing Consistent RESTful Web Service Interfaces

Petstore API - An Open Source Example

OpenAPI Specififcation

If you want to go for the full swagger codegen way there have a look at this: Open-MBEE/swagger-codegen-matlab-client

Create Read Update Delete - CRUD

Overview of RESTful API Description_Languages

HTTP methods summary table

License

My part of the cake is licensed under terms of BSD. For details please see the `license <LICENSE>`__ file of this project.

This project is dependent on code by: - urlread2 v2012

Client Code License

Show some love and leave a project link. That’s all I ask for.

Click Bait

Visitors who were interested in this repo also took a look at: swagccg-py2py - Python to Python Client Code Generator