search

Azure / API-Portal

API Portal lets you create and publish a customized site with API documentation, for free and without writing any code.
MIT License
173 stars 141 forks source link

How to add api specs by product #22

Open boyavenkatesh opened 3 years ago

boyavenkatesh commented 3 years ago

Hi There ,

we would like to categorize our apis by product . For this we are planning to define cards on home and provide a link to a product page for list of apis .

There is a api-specs folder , which is kind of generic for all pages . Is there a way to filter the list for defined page ( i.e product) .

Other issue we observed it , pages we added using admin module , can not be used as hyperlink to cards . It always says oops some thing went wrong .

Appreciate your help with this .

Cheers

azaslonov commented 3 years ago

Hi @boyavenkatesh, just to clarify, do you want to have different API spec collections/folders to be shown on different pages depending on the page path?

Regarding the error, do you mind copy it from F12 console, just to be on the same page?

boyavenkatesh commented 3 years ago

correct . for example /product1-apis will show only the specs for product1 and /product2-apis should only show porduct2 apis .

Regarding the error :

anchorUtils.ts:22 Uncaught (in promise) Error: Parameter "pageContent" not specified. at Function.getHeadingNodes (anchorUtils.ts:22) at PageSelector.eval (pageSelector.ts:125) at Generator.next () at fulfilled (pageSelector.ts:14)

azaslonov commented 3 years ago

Got it. So short answer - not out of the box. This will require some change into this operation.

Regarding the bug, looks like we fixed it in upstream libraries, so we'll merge it soon and check that issue.

boyavenkatesh commented 3 years ago

Got it . Will it be considered as future enhancement .

Cool, will wait for merge .

azaslonov commented 3 years ago

Can't promise, it looks very case-specific, but let's track it as an enhancement at least.

mikebudzynski commented 3 years ago

@boyavenkatesh, a potentially better way would be to tag APIs and then create links to the API list with a preset tag filter. Although the API list already supports passing tag filters as URL parameters, the API Portal doesn't support tags from the OpenAPI files.

boyavenkatesh commented 3 years ago

@mikebudzynski , we are looking to use Tags from Open API files , not via URL parameters . Unfortunately , API portal does not support tags from OpenAPI files as you noted.

mikebudzynski commented 3 years ago

@boyavenkatesh, I meant that the API list widget already supports applying the tag filters from the URL parameters. For example, https://contoso.com/apis#tags=testtag could automatically filter the list of APIs by the testtag tag. With this feature, you could create links to your offerings, by categorizing the APIs with tags.

Currently, the missing part is the lack of support for tags from OpenAPI files in the API Portal. For comparison, in Azure API Management's developer portal, which uses a similar widget, the tags are fetched from the API Management service and this end-to-end solution is already possible.

boyavenkatesh commented 3 years ago

@mikebudzynski got that . We are not keen to add tags as URL filter all existing APIs . Instead all put API definitions have tag element, which makes sense to use them rather adding this URL paramter.

boyavenkatesh commented 3 years ago

@boyavenkatesh, I meant that the API list widget already supports applying the tag filters from the URL parameters. For example, https://contoso.com/apis#tags=testtag could automatically filter the list of APIs by the testtag tag. With this feature, you could create links to your offerings, by categorizing the APIs with tags.

Currently, the missing part is the lack of support for tags from OpenAPI files in the API Portal. For comparison, in Azure API Management's developer portal, which uses a similar widget, the tags are fetched from the API Management service and this end-to-end solution is already possible.

@mikebudzynski as per your comment https://contoso.com/apis#tags=testtag . Do you mean to have an URL parameter called tags for every api definition in Open API file ? Or is it some thing done in Portal configuration

mikebudzynski commented 3 years ago

@mikebudzynski as per your comment https://contoso.com/apis#tags=testtag . Do you mean to have an URL parameter called tags for every api definition in Open API file ? Or is it some thing done in Portal configuration

You can assign tags to APIs in the Azure portal - it can be one tag per API or a set of tags per API. Those tags are then surfaced in the developer portal.