Use YANG descriptions where possible

[jdillard]

It would be nice if yang2swagger used the YANG description for the module and containers when one is available, similar to how it does for properties in the schema. It could fallback to the current default that it is using if one doesn't exist. This would allow for the auto-generation of documentation and other assets to have a much more polished look.

Given this example YANG model as a starting point (I had to add descriptions below) we can explore what it might look like.

module level

This can be done at the module level, where currently the yang could have:

module example-sports {

    description
    "A data model for types of sports.";

yet, the swagger has:

swagger: "2.0"
info:
  version: "1.0"
  description: "example-sports API generated from yang definitions"

call level

This may be difficult at the call level, since there aren't descriptions available for each call type in the yang. For example, in the container sports:

container sports {

    description
    "A type of sport.";

which would generate something like:

paths:
  /data/sports/:
    get:
      tags:
      - "example-sport"
      description: "returns example.sport.sports"

You could replace example.sport.sports with the description and end up with something like the following for each call:

GET:    "Returns A type of sport."
POST:   "Creates A type of sport."
PUT:    "Creates or updates A type of sport."
DELETE: "Removes A type of sport."

Instead of the current:

GET:    "Returns example.sport.sports"
POST:   "Creates example.sport.sports"
PUT:    "Creates or updates example.sport.sports"
DELETE: "Removes example.sport.sports"

I figure this could serve as a braindump for any input on how to arrive at a solution.

[bartoszm]

Good idea. Do you think you could help working on that? There is only one thing we should keep in mind. Generator allows for building single swagger for a set of yang modules.

[jdillard]

There is only one thing we should keep in mind. Generator allows for building single swagger for a set of yang modules.

I came across this when looking into the module level issue. My use case has only been converting single yangs to a single swagger, so I'm not sure the best way to represent multiple descriptions.

So far, I have mimicked the code in /swagger-generator/src/main/java/com/mrv/yangtools/codegen/SwaggerGenerator.java (IoCSwaggerGenerator.java would need the changes as well) to join multiple titles with a comma, for use in joining descriptions to replace the default generated module description, if such a replacement exists.

If you want I can submit a PR to review the code.

[bartoszm]

@jdillard please do so.

[bartoszm]

Thanks for the contribution.

[jdillard]

No problem. The call level descriptions would still be nice to add, although they are missing the necessary method(s). I think I found where to call them from, but was still looking into where to add them. If you have an idea where to add the methods I could probably submit a PR for the call level descriptions as well.