How to produce RESTCONF API Documentation based on swagger using yanger?

[bfinnema]

I have made some services in nso, which work as intended, and I would like to make swagger documentation using yanger. However, I have difficulty figuring out how to do it right so that the output from yanger is accepted by the swagger editor.

My nso is a Local install on my Mac in /Users/user1/ncs-4.7.4.1. The services are in /Users/user1/ncs-run/packages.

I have read this discussion: https://community.cisco.com/t5/nso-developer-hub-discussions/yanger-correct-formatting-of-swagger-format/td-p/3917964

And based on that I would think that my yanger command would look something like this:

yanger \
  --swagger-path-filter=/data/tailf-ncs-services:services/xxyyzz:xxyyzz \
  --format=swagger \
  -t expand \
  --output=/Users/user1/nso/swagger-restconf/xxyyzz.swagger \
  --swagger-host 127.0.0.1:8080 \
  /Users/user1/ncs-4.7.4.1/src/ncs/yang/tailf-ncs.yang \
  /Users/user1/ncs-run/packages/xxyyzz/src/yang/xxyyzz.yang
/Users/user1/ncs-run/packages/xxyyzz/src/yang/xxyyzz.yang:0: error: Too many modules given, only one data module is supported for Swagger.

Or

yanger \
  --swagger-path-filter=/data/tailf-ncs-services:services/xxyyzz:xxyyzz \
  --format=swagger \
  -t expand \
  --output=/Users/user1/nso/swagger-restconf/xxyyzz.swagger \
  --swagger-host 127.0.0.1:8080 \
  /Users/user1/ncs-run/packages/xxyyzz/src/yang/xxyyzz.yang

The last one provides an output swagger file, but it does not seem to work in swagger-editor; "root", "operations", "get", etc. sections are empty.

The yang file looks like this:

module xxyyzz {

  namespace "http://example.com/xxyyzz";
  prefix xxyyzz;

  import ietf-inet-types {
    prefix inet;
  }
  import tailf-common {
    prefix tailf;
  }
  import tailf-ncs {
    prefix ncs;
  }

  description
    "Test at GC";

  revision 2019-10-09 {
    description
      "Initial revision.";
  }

  list xxyyzz {
    description "This is an RFS skeleton service";

    key name;
    leaf name {
      tailf:info "Unique service id";
      tailf:cli-allow-range;
      type string;
    }

    uses ncs:service-data;
    ncs:servicepoint xxyyzz-servicepoint;

    leaf dev1 {
      type leafref {
        path "/ncs:devices/ncs:device/ncs:name";
      }
    }

    leaf dev2 {
      type leafref {
        path "/ncs:devices/ncs:device/ncs:name";
      }
    }

    leaf desc1 {
      type string;
      tailf:info "Type in description 1";
    }

    leaf desc2 {
      type string;
      tailf:info "Type in description 2";
    }
  }
}

(This obviously just a test service - not one of my real ones.)

I would really appreciate if you can help me figure out how to build my yanger command.

I do not find this documented anywhere. The documentation for nso and ConfD concerns this jukebox, which is really not an ncs service example. Maybe I overlooked some documentation.

I did read a bit in the swagger.io documentation, but maybe not enough.

[perander]

There are currently some limitations to the Swagger generation.

E.g. the following error says that it's only possible to generate Swagger for

one YANG module at the time.

/Users/user1/ncs-run/packages/xxyyzz/src/yang/xxyyzz.yang:0: error: Too many modules given, only one data module is supported for Swagger.

The reason it works in the linked discussion is because the service module

only augments the tailf-ncs module and doesn't contain any data nodes

itself.

Is it possible to write the service in such a way that it only augments the

/ncs:services node? E.g. could the list xxyyzz instead be augmented

under /ncs:services? If not, there might be the need to raise a feature

request for the specific use case.

The generated Swagger file seems valid since Swagger editor can consume

it, although some entries are missing, but there are a few debugging hints

when that might not be the case.

It can be valuable to check that the output from the yanger swagger plugin

produces valid JSON. Test piping it through e.g. python -m json.tool or jq.

Can some other Swagger tool consume it? E.g. swagger-ui or swagger-cli?

[gmuloche]

Hello looking at your second attempt:

yanger \
  --swagger-path-filter=/data/tailf-ncs-services:services/xxyyzz:xxyyzz \
  --format=swagger \
  -t expand \
  --output=/Users/user1/nso/swagger-restconf/xxyyzz.swagger \
  --swagger-host 127.0.0.1:8080 \
  /Users/user1/ncs-run/packages/xxyyzz/src/yang/xxyyzz.yang

Your service is actually *not* augmenting services if I am correct so have a go with:

yanger \
  --swagger-path-filter=/data/xxyyzz:xxyyzz \
  --format=swagger \
  -t expand \
  --output=/Users/user1/nso/swagger-restconf/xxyyzz.swagger \
  --swagger-host 127.0.0.1:8080 \
  /Users/user1/ncs-run/packages/xxyyzz/src/yang/xxyyzz.yang