Canvas API and Swagger

[d_tan]

Looks like Canvas is using Swagger as the API definition format. and judging by the Live API (https://<canvashost>/doc/api/api-docs.json ) it is using Swagger version 1.2

My question is does anyone know how to generate a (C#) client library based on the API definition from Swagger.

There are some options out there on the Internet like NSwag, but they all work against Swagger 2.0.

I have also tried to convert 1.2 to 2.0 using converter like https://lucybot.github.io/api-spec-converter/ , but that doesnt seem to work either.

thanks

Doug

[tnijssen]

It turns out that Canvas' API specification is just something that looks like Swagger 1.2, but doesn't actually follow the standard.

The farthest I've gotten is converting the Swagger 1.2 spec into something that looks like Swagger 2.0 (but doesn't validate, with unhelpful errors). I hadn't even gotten to the codegen phase yet.

If/when Instructure ever create API v2, maybe they can use Swagger 2.0 (or at least something that actually validates).

[matthew_buckett]

Is there any plan to update the Canvas API swagger specification to a more recent version?

[stuart_ryan · Accepted solution]

Hi  @d_tan ,

Great question, this is something I have often wondered myself.  @tnijssen , that is handy to know!

Perhaps if this is something that more people would like to see in a future version of the API, logging a feature idea for this would be outstanding. I would suggest leaving the discussion open for a while first, and then collecting all the thoughts into a feature idea, what it would deliver, and how it would benefit all who interact with the API.

Cheers,

Stuart

[stuart_ryan]

Hi  @d_tan ,

I wanted to check in and see if the previous answers have given you the information you need? For now I will mark this as assumed answered, however if you have any additional questions, please do not hesitate to jump in and let us know.

Cheers,
Stuart

[kieseld]

I would love to see Swagger 2.0 support in Canvas. Having a Swagger 2.0 spec would allow is to dynamically create clients based on the Swagger documentation. 

See:

GitHub - RSuter/NSwag: The Swagger/OpenAPI toolchain for .NET, Web API and TypeScript. 

GitHub - Azure/autorest: OpenAPI (f.k.a Swagger) Specification code generator. Supports C#, Go, Java... 

[matthew_buckett]

There was a hint from Simon Williams(Instructure) at Intrusturecarn this year that they are looking at supporting OpenAPI (upgraded and renamed Swagger API) in the future, although because their API has evolved over time, rather then being designed with Swagger/OpenAPI in mind this isn't a simple/easy process. The video of this is here:

https://www.canvaslms.com/instructurecon/video/2018/?video=mun6emoc1u 

I've managed to generate a client by upgrading the Swagger 1.2 spec to 2.0 and then tweaking it. But it needs quite a bit of tweaking to get a working client and then this progress has to be repeated when the API is changed.

[dtod]

I filed a Feature Request that I hope captures this - https://community.canvaslms.com/ideas/13768-api-in-openapi-format 

[brett_glynn_dal]

Ok so I know how to make this work but its on an API by API basis, not the whole lot at once.  

go to https://<Your Canvas DNS>/doc/api/api-docs.json 

Find the API you want in the list and cut and paste the path to replace "/api-docs.json" i.e. for users it becomes

https://<Your Canvas DNS>/doc/api/users.json 

Cut and paste that URL into Postmap Import -> "Import from link"

This will generate a Valid API collection with a couple of limitations.  All the URL's are "canvas.instructure.com" and it will import all the API's related to that.  The "user" collection for example contains EVERYTHING to do with the user even if in api.instructure.com its listed under another object.  There also appears to be undocumented API's in here I think, haven't looked closely at it yet

[dtod]

Another way is to look at the XHR requests in your browser console when you access that page, but actually, since the Requests come in with canvas.instructure.com, you can just look at https://canvas.instructure.com/doc/api/api-docs.json.

Just as an example, here's a screenshot from Postman after importing one of them. I had to edit each request to use our domain, although in fact, I use an environment variable, so the requests look like: 

https://{{domain}}/api/v1/accounts/:account_id/sub_accounts/:id‍

[dsweeney2]

Thanks Brett,

Based on this I've written a python script to collect all the API docs from the Swagger documentation and create a collection that you can import into Postman. At latest count there are 800 requests across the whole collection. Available here:

Damian Sweeney / Canvas API Postman · GitLab

Cheers,

Damian