How can I use a schema in API management developer portal?

Question

How can I use a schema in API management developer portal?

Josefine Karlsson 26

Hi!
I am experimenting with adding a schema to APIM and using the validation policy in an API to validate against that schema, and the actual validation seems to be working just fine. But when looking at the API in the developer portal, there is no example request etc that I can see. My question: in order to get a neat sample and information about the schema in the developer portal, can I somehow reference the imported schema under representation (or as a definition)? Want the validation and the information to be based on the same info and not have to update twice.

MuthuKumaranMurugaachari-MSFT 8,311 Reputation points

2022-09-02T15:02:25.367+00:00

@Josefine Karlsson Thank you for reaching out to Microsoft Q&A. Based on my understanding, you are looking to share an example request based on a schema for an API in the developer portal. Please correct me if it is incorrect.

Have you explored Example Object in the OpenAPI specification? You can add examples to parameters, properties and objects and compatible with the type schema. More examples are available here.

Sample:

The Example Object is supported in APIM during API import (API import restrictions) as well as developer portal. Checked APIM developer portal GitHub, there were few bugs reported previously and fixed in the latest release related to examples. I would recommend reviewing releases page on the latest.

Feel free to add if you have any questions. I would be happy to assist you.
Josefine Karlsson 26 Reputation points

2022-09-05T05:54:31.693+00:00

Hi!
Thanks for commenting! I have looked into this and it does not really fit my needs: I have a quite complex XML schema and one example file does not really cover all cases. Also, if the schema changes, I need to update both the schema and the example object. It would be nice to have the schema itself displayed in the developer portal so the users know what they can expect from the API validation. I hope that this will be included in the future.

MuthuKumaranMurugaachari-MSFT 8,311 Reputation points

2022-09-02T15:02:25.367+00:00

@Josefine Karlsson Thank you for reaching out to Microsoft Q&A. Based on my understanding, you are looking to share an example request based on a schema for an API in the developer portal. Please correct me if it is incorrect.

Have you explored Example Object in the OpenAPI specification? You can add examples to parameters, properties and objects and compatible with the type schema. More examples are available here.

Sample:

The Example Object is supported in APIM during API import (API import restrictions) as well as developer portal. Checked APIM developer portal GitHub, there were few bugs reported previously and fixed in the latest release related to examples. I would recommend reviewing releases page on the latest.

Feel free to add if you have any questions. I would be happy to assist you.
Josefine Karlsson 26 Reputation points

2022-09-05T05:54:31.693+00:00

Hi!
Thanks for commenting! I have looked into this and it does not really fit my needs: I have a quite complex XML schema and one example file does not really cover all cases. Also, if the schema changes, I need to update both the schema and the example object. It would be nice to have the schema itself displayed in the developer portal so the users know what they can expect from the API validation. I hope that this will be included in the future.

Answer 1

MuthuKumaranMurugaachari-MSFT 8,311

@Josefine Karlsson Thank you for your response. You can import API with schema definition in the APIM instance and add multiple examples as per OpenAPI specification. Both examples and schemas for XML payloads are displayed in the developer portal (refer Added basic XSD schema support).

Here is the sample that I created:

The schema used in the validation of policy is for runtime validation and unfortunately, we cannot reference it in the definition (has to be specified manually or automatically generated during the import like I tested above). However, by default, validate-content policy does use schema attached to API. Which means you can add validation content policy without specifying schema id that would pick default schema in the definition (refer sample request and response)

Sample
Request:

Response:

This is great feedback and would be nice to have such feature. I passed on the feedback to our product team internally. Also, I would recommend you posting it in https://aka.ms/apimwish so that others can upvote it too. I hope this answers your question and feel free to add if you have any questions. I would be happy to assist you.

Please 'Accept as answer' and ‘Upvote’ if it helped so that it can help others in the community.

Josefine Karlsson 26 Reputation points

2022-09-12T07:51:20.607+00:00

Thank you so much for taking the time to check this @MuthuKumaranMurugaachari-MSFT ! I want to try this approach but my issue is that the API I have need to be created manually (at least the first time in our dev-environment), I dont have a definition or Azure resource to generate it from. I have read the documentation for the Open API and can see that an external example object can be added with a URL, but how do I add an XSD schema to the definition?

When looking at current XML endpoints that have been generated from WSDL in our APIM instance, I can see the xsd in the developer portal, but I can't fint it referenced anywhere in the Open API-definition or in the Azure portal. Is this not possible to do manually?
MuthuKumaranMurugaachari-MSFT 8,311 Reputation points

2022-09-12T14:03:18.283+00:00

@Josefine Karlsson sure, you are welcome.

Unfortunately, you cannot add XSD schema to the definition manually. This can be achieved only through importing API which takes care of the reference automatically (WSDL in your case). Also, this will not be seen in Open-API definition but instead you can find the representation as follows:

Select API in the azure portal -> Operations (Add) -> Open form-based editor in Frontend as shown below:

Select Request to see Representations with definition name (Add)

Feel free to try and let me know if any issues.

How can I use a schema in API management developer portal?

0 additional answers

Activity