update to use OpenAPI.jl instead of Swagger.jl (#29)

* update to use OpenAPI.jl instead of Swagger.jl

* update lower bound of julia version for CI

* regenerate with support for aliases, update readme

Author: tanmaykm

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.3'
+          - '1.6'
           - '1' # automatically expands to the latest stable 1.x release of Julia
           - nightly
         os:

.gitignore

@@ -1,3 +1,4 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+openapi-generator-cli.jar

Project.toml

@@ -2,7 +2,7 @@ name = "Azure"
 uuid = "34b51195-c7f2-5807-8107-6ca017e2682c"
 keywords = ["azure", "cloud", "api", "julia"]
 desc = "Julia interface to Azure APIs"
-version = "0.4.1"
+version = "0.5.0"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
@@ -12,18 +12,20 @@ JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 MbedTLS = "739be429-bea8-5141-9913-cc70e7f3736d"
 Mmap = "a63ad114-7e13-5084-954f-fe012c677804"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
-Swagger = "2d69052b-6a58-5cd9-a030-a48559c324ac"
+OpenAPI = "d5e62ea6-ddf3-4d43-8e4c-ad5e6c8bfd7d"
+TimeZones = "f269a46b-ccf7-5d73-abea-4c690281aa53"
 XMLDict = "228000da-037f-5747-90a9-8195ccbf91a5"
 URIs = "5c2747f8-b7ea-4ff2-ba2e-563bfd36b1d4"
 
 [compat]
 Downloads = "1"
-Swagger = "0.3"
+OpenAPI = "0.1"
 XMLDict = "0.3,0.4"
 JSON = "0.21"
 MbedTLS = "0.6.8, 0.7, 1"
-URIs = "1.3"
-julia = "1.3"
+TimeZones = "1"
+URIs = "1.3, 1.4"
+julia = "1.6"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -1,12 +1,12 @@
 # Azure.jl
 
-A Julia library to access Microsoft Azure REST APIs. Most code in this file is generated automatically using [Swagger.jl](https://github.com/JuliaComputing/Swagger.jl)
+A Julia library to access Microsoft Azure REST APIs. Most code in this file is generated automatically using [OpenAPI.jl](https://github.com/JuliaComputing/OpenAPI.jl)
 
 [![Build Status](https://github.com/JuliaComputing/Azure.jl/workflows/CI/badge.svg)](https://github.com/JuliaComputing/Azure.jl/actions?query=workflow%3ACI+branch%3Amaster)
 
 ```
 using Azure
-using Swagger
+using OpenAPI
 using Azure.StorageManagementClient
 using Azure.StorageServices
 using Azure.ComputeManagementClient
@@ -44,22 +44,48 @@ ctx = AzureContext(creds)
 
 # Call APIs
 
-## List operations
+Each API client module has corresponding API methods that can be invoked by providing an instance of the API and the API version.
+
+The `api` method returns an instance of the API. E.g.: `api(ctx, StorageManagementClient.OperationsApi)`.
+
+The `apiver` method returns the version of the API. E.g.: `apiver(StorageManagementClient.OperationsApi)`
 
+The API methods return a tuple of the decoded response value and the associated HTTP response object.
+The `Azure.check_api_response` method can be used to examine the HTTP response and either throw an exception
+(`Azure.AzureException`) on error or return the response value on success. E.g.:
+
+```julia
+list = Azure.check_api_response(StorageManagementClient.operations_list(
+    api(ctx, StorageManagementClient.OperationsApi),
+    apiver(StorageManagementClient.OperationsApi)
+  ))
 ```
-StorageManagementClient.operationsList(api(ctx, OperationsApi), apiver(OperationsApi))
 
-ComputeManagementClient.operationsList(api(ctx, ComputeOperationsApi), apiver(ComputeOperationsApi))
+## List operations
+
+```julia
+Azure.check_api_response(StorageManagementClient.operations_list(
+    api(ctx, StorageManagementClient.OperationsApi),
+    apiver(StorageManagementClient.OperationsApi)
+  ))
+
+Azure.check_api_response(ComputeManagementClient.operations_list(
+    api(ctx, ComputeManagementClient.ComputeOperationsApi),
+    apiver(ComputeManagementClient.ComputeOperationsApi)
+  ))
 ```
 
 ## Get a VM and list out some of its attributes
 
-```
+```julia
 const subscription_id = "subscrip-tion-idxx-xxxx-xxxxxxxxxxxx"
-vm = virtualMachinesGet(api(ctx, VirtualMachinesApi), 
-                        "test-resource-grp", "my-vm-name", 
-                        apiver(VirtualMachinesApi), 
-                        subscription_id)
+vm = Azure.check_api_response(virtual_machines_get(
+    api(ctx, ComputeManagementClient.VirtualMachinesApi), 
+    "test-resource-grp",
+    "my-vm-name", 
+    apiver(ComputeManagementClient.VirtualMachinesApi), 
+    subscription_id
+  ))
 
 vm_props = vm.properties
 vm_osdisk = vm_props.storageProfile.osDisk
@@ -73,7 +99,7 @@ nicids = [rsplit(nicid, '/'; limit=2)[2] for nicid in map(nicref->nicref.id, nic
 
 ## File share operations
 
-```
+```julia
 const resource_group_name = "testresgroup"
 const fileshare = "https://mystorage.file.core.windows.net/myshare?restype=share"
 success = createShare(ctx, subscription_id, resource_group_name, fileshare, "100", Dict("taname"=>"taval"))
@@ -84,14 +110,14 @@ deleteShare(ctx, subscription_id, resource_group_name, fileshare)
 
 ## SAS operations
 
-```
+```julia
 const blob = "https://mystorage.blob.core.windows.net/testblob/myblob.dat"
 appendSAS(ctx, subscription_id, resource_group_name, blob)
 ```
 
 ## File blob operations
 
-```
+```julia
 const storageaccount_url = "https://mystorage.blob.core.windows.net/"
 const testcontainer = storageaccount_url * "testcontainer1"
 
@@ -121,11 +147,16 @@ More examples [test/test_blobs.jl](here).
 
 ## Rate card
 
-```
+```julia
 ratefilter = join(["OfferDurableId eq 'MS-AZR-0003p'",
                    "Currency eq 'USD'",
                    "Locale eq 'en-US'",
                    "RegionInfo eq 'US'"],
                    " and ")
-rates = rateCardGet(api(ctx, RateCardApi), ratefilter, apiver(RateCardApi), subscription_id)
+rates = Azure.check_api_response(rate_card_get(
+    api(ctx, UsageManagementClient.RateCardApi),
+    ratefilter,
+    apiver(UsageManagementClient.RateCardApi),
+    subscription_id
+  ))
 ```

gen/generate.jl

@@ -1,11 +1,7 @@
 using Logging
 
 const DIR = dirname(@__FILE__)
-const GENDIR = joinpath(DIR, "..")
-const TEMPCFGFILE = joinpath(GENDIR, "config.json")
-const SRCDIR = joinpath(GENDIR, "src")
-const SWAGGERDIR=read(`$(joinpath(Sys.BINDIR, "julia")) -e 'import Swagger; print(normpath(joinpath(dirname(pathof(Swagger)), "..")))'`, String)
-const SWAGGERGEN = joinpath(SWAGGERDIR, "plugin", "generate.sh")
+const SRCDIR = abspath(joinpath(DIR, "..", "src"))
 
 const SPECS = [
     ("DataLakeStoreAccountManagementClient",    "DataLakeStore",    "2016-11-01",           "specification/datalake-store/resource-manager/Microsoft.DataLakeStore/stable/{VER}/account.json"),
@@ -36,25 +32,21 @@ const SPECS = [
     ("PolicyAssignmentsClient",                 "Resource",         "2019-09-01",           "specification/resources/resource-manager/Microsoft.Authorization/stable/{VER}/policyAssignments.json"),
     ("PolicyDefinitionsClient",                 "Resource",         "2019-09-01",           "specification/resources/resource-manager/Microsoft.Authorization/stable/{VER}/policyDefinitions.json"),
     ("PolicySetDefinitionsClient",              "Resource",         "2019-09-01",           "specification/resources/resource-manager/Microsoft.Authorization/stable/{VER}/policySetDefinitions.json"),
-    ("UsageManagementClient",                   "Commerce",         "2015-06-01-preview",  "specification/commerce/resource-manager/Microsoft.Commerce/preview/{VER}/commerce.json")
+    ("UsageManagementClient",                   "Commerce",         "2015-06-01-preview",  "specification/commerce/resource-manager/Microsoft.Commerce/preview/{VER}/commerce.json"),
 ]
 
-const PATCHES = Dict(
-    ("ComputeManagementClient", "Compute") => ["model" => ("Caching", "CreateOption", "StorageAccountType")],
-    ("ResourceManagementClient", "Resource") => ["model" => ("DeploymentPropertiesExtended",)]
-)
-
 const MODULE_HEAD = """module Azure
 
-using Swagger
+using OpenAPI
 using Downloads
 using JSON
+using URIs
 
 # API versions
 const _module_versions = Dict{Module,String}()
 const _api_versions = Dict{DataType,String}()
 
-# include Azure REST protocol (not Swagger)
+# include Azure REST protocol (not OpenAPI)
 include("rest_api_protocol.jl")
 
 # inlcude sub modules for individual API groups"""
@@ -68,65 +60,51 @@ include("helper.jl")
 
 end # module Azure"""
 
-function genunit(pkg, grp, swg)
-    open(TEMPCFGFILE, "w") do f
-        println(f, """{ "packageName": "$pkg" } """)
-    end
-    outpath = joinpath(SRCDIR, grp)
-    pkgpath = joinpath(outpath, pkg)
-    mkpath(pkgpath)
-    run(`$SWAGGERGEN -i $swg -o $outpath -c $TEMPCFGFILE`)
-    for outfile in readdir(joinpath(outpath, "src"))
-        outfile_from = joinpath(outpath, "src", outfile)
-        outfile_to = joinpath(pkgpath, outfile)
-        @debug("moving $outfile from $outfile_from to $outfile_to")
-        mv(outfile_from, outfile_to)
-    end
-    rm(joinpath(outpath, "src"); force=true)
-    rm(joinpath(outpath, "REQUIRE"); force=true)
-    rm(joinpath(outpath, "LICENSE"); force=true)
-    rm(joinpath(outpath, ".swagger-codegen-ignore"); force=true)
-    rm(joinpath(outpath, ".swagger-codegen"); force=true, recursive=true)
-    rm(TEMPCFGFILE; force=true)
-
-    # apply patches if any
-    patches = get(PATCHES, (pkg,grp), [])
-    for patch in patches
-        patch_type, names = patch
-        for name in names
-            patchfile = patch_type * "_" * name * ".jl"
-            cp(joinpath(DIR, patchfile), joinpath(pkgpath, patchfile); force=true)
-        end
-    end
+function commands(pkg, outpath, specfile)
+    # add --global-property debugModels=true to turn on model debug output
+    gencmd = `java -jar openapi-generator-cli.jar generate -i $specfile -g julia-client -o $outpath --additional-properties=packageName=$pkg`
+    cleancmd = `rm -rf $outpath`
 
-    # return the module file to include
-    module_file = joinpath(grp, pkg, pkg * ".jl")
+    return cleancmd, gencmd
+end
+
+function genunit(pkg, grp, specfile)
+    outpath = joinpath(SRCDIR, grp, pkg)
+    pkgpath = joinpath(outpath, pkg)
+    # mkpath(pkgpath)
+    cleancmd, gencmd = commands(pkg, outpath, specfile)
+    run(cleancmd)
+    run(gencmd)
+
+    #    # return the module file to include
+    module_file = joinpath(outpath, "src", pkg * ".jl")
+    apispath = joinpath(outpath, "src", "apis")
     apinames = String[]
-    for f in readdir(joinpath(outpath, pkg))
-        if startswith(f, "api_")
-            apiname = split(split(f, '_')[2], '.')[1]
-            push!(apinames, apiname)
+    if isdir(apispath)
+        for f in readdir(apispath)
+            if startswith(f, "api_")
+                apiname = split(split(f, '_')[2], '.')[1]
+                push!(apinames, apiname)
+            end
         end
     end
     module_file, apinames
 end
 
-function gen(swgroot)
+function gen(openapiroot)
     mkpath(SRCDIR)
 
-    for spec in SPECS
-        pkg, grp, ver, swg = spec
-        grppath = joinpath(SRCDIR, grp)
-        rm(grppath; recursive=true, force=true)
-    end
-
     open(joinpath(SRCDIR, "Azure.jl"), "w") do azf
         println(azf, MODULE_HEAD)
 
         for spec in SPECS
-            pkg, grp, ver, swg = spec
-            swg = replace(swg, "{VER}"=>ver)
-            mod, apinames = genunit(pkg, grp, joinpath(swgroot, swg))
+            pkg, grp, ver, openapispec = spec
+            openapispec = replace(openapispec, "{VER}"=>ver)
+            mod, apinames = genunit(pkg, grp, joinpath(openapiroot, openapispec))
+            # mod returned will be absolute path, so would be SRCDIR
+            # create relative path for inclusion in .jl file
+            mod = relpath(mod, SRCDIR)
+            
             println(azf, "include(\"", mod, "\")")
             println(azf, "_module_versions[$pkg] = \"$ver\"")
             for apiname in apinames