Azure-rest-api-specs: Make ApiSchema GET Contract consistent for all api Types

[solankisamir]

Because of the weirdness, clients have to write custom code to extract the exact schema

application/vnd.ms-azure-apim.swagger.definitions+json

{
   "properties" : {
    "contentType": "application/vnd.ms-azure-apim.swagger.definitions+json",
    "document" : "json schema here"
    }
}

But for application/vnd.ms-azure-apim.xsd+xml or application/vnd.oai.openapi.components+json or application/vnd.ms-azure-apim.wadl.grammars+xml

{
   "properties" : {
    "contentType": "application/vnd.ms-azure-apim.swagger.definitions+json",
    "document" : {
          "value" : "api schema here"
         }
    }
}

[wasfree]

Is there a approximate ETA on this?

[solankisamir]

we are planning to release this change in the api-version 2019-08-01, which should go out by the end of September 2019. We are clubbing multiple other changes and hence it will take time.

[tombuildsstuff]

@solankisamir is there a timeline for when this'll become available in the Swagger too?

[solankisamir]

@tombuildsstuff, this got delayed and we are just starting on it on the service side changes

[arifsundrani]

@solankisamir any updates?

[timja]

Any updates @solankisamir?

[J0F3]

@solankisamir any news? Is there an approximate ETA when we can expect a fix?
Seem the resolution of multiple issues and improvements in the Azure Terrafrom provider are blocked because of that one here. 😢

Thx!

[vfedonkin]

The implementation (and data returned) will stay exactly the same, but the documentation/specification will be changed.

Instead of 2 current contracts specifications:
"contentType": "",
"document":
and
"contentType": "",
"document":
{
"value":"",
}

We will have only one:

{
"properties" : {
"contentType": "application/vnd.ms-azure-apim.swagger.definitions+json",
"document" : {
"value" : " (api schema if not JSON based) "
"definitions" : { (JSON object descriping types definitions if JSON based (swagger or openApi)) }
}
}
}

So new contract may contain either "value" or "definitions" filled depending on the content type.
It already works this way right now, but documentation is just unclear.

[vfedonkin]

The documentation changes should be released till the end of the year.

[evertonmc]

The documentation changes should be released till the end of the year.

Any place we can track the progress besides here?

[J0F3]

First of all: Happy new year! 😊🎉

The documentation changes should be released till the end of the year.

Which brings me directly to my question. As end of the year is now over 😉 what is the current progress of this?

Because multiple issues of resources in the Azure Terraform Provider are blocked by this I am very curious when this get finally fixed.

Thx
Jonas

[vfedonkin]

The documentations update completed month or two ago, but it's still in review/publishing stage. At the same time, the question: why it blocks the customer? The documentation changes were described above, so it can be sent to the customer now.

[J0F3]

Good question.
@tombuildsstuff or @solankisamir can you please elaborate a bit why this issue here is still blocking several issues in the Azure Terraform Provider Project.
For example: terraform-providers/terraform-provider-azurerm#5096

Thx!

[vfedonkin]

@J0F3 , I checked the item you asked about. In addition to the documentation, customer is using the Azure SDK generated by the specs, which are not updated yet. Specs will be updated together with the documentation. So customer will need to wait till we released 2019-12-01 version. Plan was 01/01/2020 but postponed because of release freezes / reviews.

[J0F3]

Ah ok. Thank you @vfedonkin you for looked into it.

[mcalster]

Hi @vfedonkin do you know what kind of timeline we can expect on the release?

[arifsundrani]

@mcalster I believe #8066 was the pull request associated to these changes. There was a premature merge of the PR that needs to be reverted.

[mcalster]

@mcalster I believe #8066 was the pull request associated to these changes. There was a premature merge of the PR that needs to be reverted.

Ok, the PR merge has been reverted, any idea of when the "intended merge" will happen? We are currently building a pipeline to push open-api specs with terraform. We don't want to revert to swagger 😉

[arifsundrani]

@mcalster I have been following and #8225 will address the items at the end of 8066. I do not know of a timeframe as to when the changes will finally be pushed. I am eagerly awaiting these changes as well.

Thanks @solankisamir & @vfedonkin for your hard work, we really appreciate it!

[hctv19]

@arifsundrani It looks like https://github.com/Azure/azure-rest-api-specs/pull/8225 was merged on Jan 29th. Does that merge unblock this issue?

[arifsundrani]

@hctv19 I’m not sure as I am just following along. I believe @solankisamir would be able to answer your question.

[vfedonkin]

Not yet. This PR is also required before we can regenerate SDK: #8393

[hctv19]

@vfedonkin looks like they finally got #8393 merged, so I think this should be unblocked now

[hctv19]

Also gently pinging @solankisamir on this PR since #8393 has been resolved

[hctv19]

@solankisamir @vfedonkin Is there anything else needed before this can be approved and merged?

[Harmindersingh05]

Any update on this? This is the only item that is required to support API Management consumption model via terraforms.

[vfedonkin]

@Harmindersingh05, just yesterday we got signed all required PRs and now preparing the nuget package. Should be ready in nearest days.

[solankisamir]

The fix is available at following locations
REST API doc; https://docs.microsoft.com/en-us/rest/api/apimanagement/2019-12-01/apischema/createorupdate

.NET SDK :
https://www.nuget.org/packages/Microsoft.Azure.Management.ApiManagement/5.0.0-preview
ChangeLog; https://aka.ms/apimdotnetsdkchangelog

Python SDK
https://pypi.org/project/azure-mgmt-apimanagement/0.2.0/

JS SDK
https://www.npmjs.com/package/@azure/arm-apimanagement/v/6.0.0

Go SDK
https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/services/apimanagement/mgmt/2019-12-01/apimanagement?tab=doc