1.8-rc1 Docker & swagger usage

Developer Experience
1

I am exploring 1.8rc-1 and have a docker install running with a single windows client.

What I want to do is look at the APIs for the CMS, and it appears that swagger will do what I want. However, I am not that familiar with both docker and swagger so need some pointers.

I have swagger-ui installed on my server and it tests fine with the pet store demo data. I have the XIBO docker at port 8080 and if I go to http://localhost:8080/swagger.json with Firefox I get a json document,

If I startr swagger on the locahost and try to invoke swagger.json for 1.8 I get errors.

Suggestions?

2

What errors do you get?

We use swagger for documentation purposes only, so you can look at the static docs in the online manual without missing out on any extra info.

3

From browser I can get data at localhost:8080/swagger.json

start swagger.
put http://localhost:8080/swagger.json
error message:
Can’t read from server. It may not have the appropriate
access-control-origin settings.

I want to explore the API using swagger, ie. make changes and see them
react on my client,

4

You have to send the correct headers for your browser to be able to load data from the side. You do this by sending things like the CORS headers: enable cross-origin resource sharing

5

With a docker should it not be already set for that.

6

As I said, we use swagger for documentation purposes only and this will not work. Although it looks like swagger has been updated to support the application flow since we started working with it - so perhaps this is now possible (not without changes)

Same reason for why it is not installed with Docker.

Start swagger on the localhost? What swagger tool are you using? swagger-ui? If so you need to host swagger locally - drop it in $DATA_DIR/shared/cms/web/userscripts and then access it from http://localhost:8080/userscripts/your_swagger_folder

7

No, the CORS headers basically white list things like applications that are hosted eg. through ads or third parties on a website from a different domain. Not having CORS headers, most browsers will just block 3rd party applications. If Swagger is a 3rd party application hosted on a “different” domain, the browser will block it.

It’s a browser setting, the CORS headers allow the website to whitelist additional domains but it’s very unsafe to just whitelist everything.

You can modify the Docker application to include/allow any domain or specifically your Swagger application. Just connect to the Docker instance, go in the nginx or Apache configuration and modify and restart.

8

OK…that worked well, I can now look at the operations for the API… However, it sure would be nice if you could also try those operations out as swagger will allow you to. I tried it and ran into an authorization problem. Have you got a pointer an where I can start working on this?

9

You’d need to add a security definition for it in the swagger.json file: https://github.com/xibosignage/xibo-cms/blob/develop/web/swagger.json#L6338

I’ve only documented the accessCode flow at present, which doesn’t seem to work correctly through swagger-ui.

Xibo also supports client_credentials, which swagger call “application”. So if you documented that flow, it may well work.