Referring to groups of REST APIs in Swagger

[Nathan Sowatskey]

Hi

I would like to be able to provide an URL for the Swagger documentation for all of the, say, "Network Plug and Play" APIs, of which there are three.

As matters stand now, I think I have to do something like this:

"The Swagger documentation for the topology APIs may be seen in the lab at https://192.168.1.13/swagger#!/pnp-device, https://192.168.1.13/swagger#!/pnp-file and https://192.168.1.13/swagger#!/pnp-project."

That is clearly unwieldy, so I would rather do something like this:

"The Swagger documentation for the topology APIs may be seen in the lab at https://192.168.1.13/swagger#!/ztd"

But there does not seem to a form of a URL like that which works. If I try the base URL I just get "Error Happened".

Any ideas please?

Many thanks

Nathan

[yawming]

Hi Nathan,

From where you can this - https://192.168.1.13/swagger#!/ztd" ?

Can you please use Login - APIC - Enterprise Module to show?

Thanks,

Yawming

[Nathan Sowatskey]

Hi Yawming

Thanks for following up.

I can't actually use "https://192.168.1.13/swagger#!/ztd". That is an example of what I would like to do, where that URL shows all of the PnP APIs that I have to refer to individually above.

Regards

Nathan

[aradford]

not sure that makes sense:

1. You should be referring to PnP not ZTD (that was legacy term, i know "ztd"  is still embedded in DTO, but high level construct is PnP)
2. PnP process  involves a range of API that are in different subsystems.  It also needs /file which is where all the config and image files are stored.  PnP ends up impacting /network-device as a completed device ends up in inventory.   where do you draw the line?
3. If you think about workflows, there are two use cases
   • project workflow ---- which uses /pnp-project
   • unclaimed workflow --- which uses /pnp-device

i have found it easier to take people down a workflow and map that into API rather that the other way around...

[Nathan Sowatskey]

Adam

Many thanks for following up. I am sorry that I am not explaining myself properly.

The attached image, hopefully, will illustrate my question. I have clicked on "Network Plug and Play". The browser URL is apparently unchanged. The base URL illustrated at the bottom does not work.

I want to be able to refer to the group of APIs in the attached diagram with a single URL. As matters stand now, I have to do something like this:

"The Swagger documentation for the Network Plug and Play APIs may be seen in the lab at https://192.168.1.13/swagger#!/pnp-device, https://192.168.1.13/swagger#!/pnp-file and https://192.168.1.13/swagger#!/pnp-project."

Note that this is just a convenience to refer to a group of APIs, not a means to explain how to use them, or a means to explain the overall process.

In any case, I suspect that the Swagger documentation simply does not support this. If that is the case, then perhaps this should just be passed to the development team as a feature request?

Regards

Nathan

P.S. I have also realised that my original example might have been misleading, using the word "Topology" when I meant "Network Plug and Play". Sorry about that.

[aradford]

I understand.  We are using an old version of swagger, and that needs to be upgraded.  I see your point about being able to just get a sub-grouping of API.

Just be careful with your example here:

For example: a common misconception is that /pnp-file is used for configuration/image files.  It is not.

The /file service (the general file service, under "File") is a very important part of PnP as that is where the config and image files are stored.  i.e. nothing to do with /pnp-file.

Developers will interact with multiple services to build a use case.

[Nathan Sowatskey]

Thanks. I have updated my text to say:

The Swagger documentation for the Network Plug and Play APIs may be seen in the lab at https://192.168.1.13/swagger#!/pnp-device, https://192.168.1.13/swagger#!/pnp-file and https://192.168.1.13/swagger#!/pnp-project. Also see https://192.168.1.13/swagger#!/fileservice.