FR: Swagger-ui

[Angelblue05 4130]

This is a simple request about swagger-ui. I've been unable to load swagger-ui with one click. It's a minor inconvenience, granted but I feel this process could maybe be simplified somehow.

 

The loading address is incorrect as you can see, I always need to delete "/swagger-ui" in the url field. Is there a way to correct this so it loads properly the first time? Also, is there a way to "pre-populate" the api key field with a generated api key of ours? Since there's no way to bookmark it while keeping the proper information for later, I have to repeat the steps every single time. Am I missing something?

 

[Angelblue05 4130]

Also, with the addition of the api key to the URL, it seems to have broken anything that's in between curly brackets {}. It does not get replaced with information in the fields.

Edited March 12, 2015 by Angelblue05

[Angelblue05 4130]

The "Can't read swagger JSON' error is back. I don't know when it stopped working. Also, the api key pre-loaded doesn't work. I get unauthorized in the api response, unless I manually add an api key at the top, which I have manually generated on my server.

[Luke 37046]

Swagger will be back for the next release and will look better than ever:

 

 

[sampsonight 4]

 

 

Swagger will be back for the next release and will look better than ever:

 

Can't wait!

[Luke 37046]

In the latest beta server you can browse the endpoints, and you can execute some of them.

[harrv 88]

Thank you! I often want to create custom integrations between Emby and other components of my home theater system. Trying to do so without a well-documented API has been difficult. I appreciate your recent improvements in this area!

[harrv 88]

In the current stable server release (3.2.36.0) at the URL Luke previously gave us (http://localhost:8096/swagger) I don't see a Swagger-UI but I do see the JSON definition for the API. (Let me know if Swagger-UI is integrated and I just have the URL wrong.)

In the meantime, until Swagger-UI is integrated with Emby Server, in case it is helpful to others I just wanted to point out two ways of viewing the Emby API definition in an external, online Swagger-UI.

1. If your Emby server has a public-facing URL (that isn't blocked by a router, NAT, or firewall) you can use the following URL to see the Emby API documentation in a full Swagger-UI:
 

http://petstore.swagger.io/?url={url-to-your-json-swagger-def-file}

For example, if I could access my Emby server publicly at
 

https://myembyserver.com/

then the URL I would use to see the API doc is
 

http://petstore/swagger.io/?url=https://myembyserver.com/swagger

2. If your Emby server doesn't have a public-facing URL, you can still view the documentation in a Swagger-UI by first browsing to the JSON definition file and copying the whole thing, then go to the following URL and paste the JSON in the pane on the left side of your browser window (replacing what is already there): https://editor.swagger.io/
 
The online editor will then parse the Emby Server API definition, and display the Swagger-UI view of the API in the right side of your browser window. At the top, you'll probably see an Errors section, which you can hide.

Having access once again to the API documentation is pretty great! I hope Emby Server continues to publish the definition, even if there is some issue with integrating Swagger-UI directly. Thanks.

[Luke 37046]

there is a link to it in the server dashboard.

[harrv 88]

there is a link to it in the server dashboard.

 

Ah, there sure is. Thanks!

 

I see you went with running your own instance of the Swagger-UI on emby.media, rather than embed it with every instance of Emby Server. That's probably a good idea.

 

This works well for reading the doc, which is primarily what I wanted to do.

 

I can't get the "try it out" buttons to work because of what looks like several issues, but that's not a huge deal because I can use Postman, or curl, or write code to try stuff.

 

But in case you want to see what I mean about "try it out", I'll mention a couple things I saw:

 

1. The only listed scheme in the published swagger.json from my server is HTTP, even though the public interface is HTTPS. So all of the "try it out" buttons use HTTP, which fails.

 

For what it's worth, my in-home (LAN) URL is HTTP. But if I access it that way and then hit the "API" link on the server dashboard, the Swagger-UI shows the single error, "Failed to load spec." Presumably, that happens because loading the JSON spec is a server action attempted by swagger.emby.media (which does not have access to a LAN-only URL) rather than a browser action (which would).

 

2. Even if the scheme issue were solved, I don't think "try it out" would be able to do much more than maybe get /System/Info/Public because there doesn't seem to be any way to provide the necessary values that go into the path, such as {Id} or {Key}. It's not recognizing those as parameters that the user can provide.

 

Thanks again for your reply and for publishing the API spec from the server again.

[Luke 37046]

Thanks, good point about https. I think we may have moved to swagger 3.x too quickly as I don't think the html supports all the different authentication methods yet. In any case, we're too far in at this point so I don't want to go back to 2.x. We may just have to wait. I'll re-evaluate the latest version soon to see if anything has changed.

[picovidago 0]

Hello, I'm new to emby, can you tell me how can I authenticate to the emby server and use swagger afterwards?