I have a server that I generate dynamically from a template, and it exposes an API rooted at /api. I only access it with HTTPS. If I specify the baseUrl as "/api", swagger-ui tries to access /api but with HTTP (and my browser says "locked loading mixed active content").
If I give https://hostname/api as the basePath things work fine, but I don't want the JSON file to be different for each server.
Any ideas?
Thanks, Yaron
Even if the OP have already found the answer, others may not, so I'll try to answer. You should specify schemes property (Swagger 2.0):
{
"swagger": "2.0",
"schemes": [ "https" ]
}
If you just leave the schemes property blank, swagger-ui will use the same scheme used to access the swagger.json file.
From the docs:
If the schemes is not included, the default scheme to be used is the
one used to access the Swagger definition itself.
Related
I am using v-file-input with 'accept' option, e.g.
<v-file-input
:accept=".docx, .txt, image/* ",
label="Choose Attachment"
name="file0"
id="file0"
></v-file-input>
This works and does not allow a file to be selected outside the defined 'accept' file types. The question is that is it still recommended to check for the valid file extension at the server?
Yes, most frontend validations for data being added to an endpoint request can be bypassed by making the request outside of your app using programs like Postman. Setting up CORS on your backend can mitigate that specific risk... However, you can never be too safe. If it's a security risk or concern at all, always validate on the backend.
What is the standard outcome of the following 'remove' JSON Patch with an empty "" path?
[{ "op": "remove", "path": ""}]
Should it clear the whole object, equal to assigning {}? In http://jsonpatch.com/ it says: To point to the root of the document use an empty string for the pointer. So I guess a 'remove' on the root removes the whole object, right?
I tried it with two different JSON Patch libraries with two different results:
https://github.com/java-json-tools/json-patch: deletes the whole object
https://github.com/gnieh/diffson: throws an JsResultException
What is the officially accepted, standard outcome of this? I checked in the RFC for the JSON Patch (https://www.rfc-editor.org/rfc/rfc6902) but couldn't find anything.
RFC 6902 references this for further error handling: https://www.rfc-editor.org/rfc/rfc5789#section-2.2
And to me, this part seems to fit the bill:
Resource not found: Can be specified with a 404 (Not Found) status
code when the client attempted to apply a patch document to a non-
existent resource, but the patch document chosen cannot be applied
to a non-existent resource.
Since you basically did not define any resource - not even / which would more clearly refer to the root / the entire object.
I guess the difference in the two libraries comes from that these two are usually considered identical:
/my/resource
/my/resource/
But usually the non-/ path would be automatically 301 Redirected to the path that does have /. So I would personally go with the 404 response for "path": ""
I want to use swagger with different hostnames but keep the same description file. How is this possible, For example, I tried an empty string for host and listed the schemes, but that did not work.
"host": "",
"schemes": [ "http" ],
Put markers like ${host} in your swagger definition file and process it with a template processor of your choice (perl script, Apache Velocity, Apache Freemarker, Maven resource processing, etc.).
An alternative approach that just came to my mind yet I have not tried myself involves using Postman extension for Google Chrome browser and its environmental variables. Postman can import swagger files into request collections and supports definition of environmental variables (see https://www.getpostman.com/docs/environments) for use in requests. Now, if you write the markers in the swagger definition file using the syntax notation of Postman and name those equal to your defined variables, you can keep requests and environment separated in Postman and you can change and reimport the swagger definitions anytime.
swagger.js has to be modified to accept host option. swagger-UI passes options to swagger-js and it accepts a 'spec' parameter.The hosting page can load the swagger.json file by simply parsing it as JSON.parse.
Set 'host' in it and then pass it to swaggerUi constructor.
I would like you to go through the link once.
Allow host to be specified
Hope it helps you in understanding.
Please provide me some references to call WebScripts in alfresco remotely using JSON..
Alfresco has some default Webscripts ,I need to invoke these Webscripts in different Application remotely...
There is no documentation that I know of at the present time that documents all web scripts that expect JSON to be posted along with a schema that defines the expected JSON. Honestly, we haven't done a good job identifying which out-of-the-box URLs are actually public. Some are there just for the Share application's use and could change without warning.
With that said, you can go to http://localhost:8080/alfresco/s/index and see a list of web scripts. And if you drill down into the web script (click on the web script's ID), you can see the source code for the JavaScript controller or, if the web script is implemented in Java, you can see the full class name that implements it. You can then inspect the source to see what it is expecting.
Another way to do it is to use Firebug or your browser's developer console to watch the network calls that go from your browser to the repository tier. Many of these calls include JSON being posted to repository tier web scripts.
Assuming you're referring to getting a webscript to respond with a json, there are a few steps.
1. Create a webscript, and possibly set json the default format (in the webscript definition file, i.e. mywebscript.get.desc.xml, add a tag
<format default="json">argument</format>
Create a JSON controller too, ie. mywebscript.get.json.js. This script can do two things:
a) get json parameter (if you sent a json in): if (json.has('myparam')) myVar = json.get('myparam');
b) provide some data to the model, ie. model.docs = companyhome.children
Your webscript also needs to format this json for json response, i.e. mywebscript.get.json.ftl would look something like this:
{ "docs": [
<#list docs as doc> {
"name": "${doc.name}",
"prop": "${doc.properties["mymodel:myprop"]}"
} <#if doc_has_next>,</#if>
</#list>
]
}
The Sun Cloud API at http://kenai.com/projects/suncloudapis/pages/Home is a good example to follow for a RESTful API. True to RESTful principles, when you GET a resource you get no more nor less than a representation of that resource.
The Content-Type header in the response tells you exactly what the type of that resource is, for example application/vnd.com.sun.cloud.Snapshot+json. Sun has registered these mimetypes with the IANA.
How practical is this in general currently? Most API's I have seen have used the Content-Type of "application/json". This tells you that the response is JSON but nothing more about it. You have to have something in the JSON object, like a "type" property, to know what it is.
I'm designing a RESTful API (which will not be made public, therefore I wouldn't be registering mimetypes). I have been using RESTEasy and I find that even if I specify a complete mimetype, the Content-Type in the response header will be exactly what the Accept request header specified. If the request asks for "application/*+json" by default the response header will have "application/*+json". I can probably fix this by changing the header before the response goes out, but should I try to do that? Or should the response have a wildcard just like the request did?
Or should I just serve up "application/json" like most APIs seem to do?
Additional thoughts added later:
Another way of stating the question is: Should I use HTTP as the protocol, or should I use HTTP only as a transport mechanism to wrap my own protocol?
To use HTTP as the protocol, the entity body of the response contains the representation of the object requested (or the representation of an error message object), the "Content-Type" header contains the exact type of the object, and the "Status" header contains a success or error code.
To use HTTP as merely a transport mechanism, the "Status" header is always set to 200 OK, the "Content-Type" is something generic like "application/json", and the entity body contains something that itself has an object, an object type, an error code and whatever else you want. If your own protocol is RESTful, then the whole scheme is RESTful. (HTTP is a RESTful protocol but not the only possible one.)
Your own protocol will be opaque to all the transport layers. If you use HTTP as the protocol, all the transport layers will understand it and may do things you don't want; for instance a browser will intercept a "401 Unauthorized" response and put up a login dialog, even if you want to handle it yourself.
I use my own vnd.mycompany.mymediatype+xml media types for many of my representations. On the client I dispatch to the appropriate controller class based on the media type of the returned representation. This really allows the server to control the behavior of my client application in response to the user following a link.
Personally, I believe that using application/xml and application/json are one of the worst choices you can make if you hoping to support REST clients. The only exception to this is when the client only uses downloaded code (like Javascript) to interpret the data.
Or should I just serve up "application/json" like most APIs seem to do?
I don't think so.
A media type is the only point of coupling between your RESTful web application and the clients that use it. The documentation of your media types is the documentation of your API. Your media types are the contract between your clients and your application. Eliminate the specific media type and you eliminate an important element that makes REST workable.
Sun has registered these mimetypes with the IANA.
Couldn't find any mention of that here. AFAIK, there is no requirement to actually register your custom media type with the IANA. The convention seems to be to use the inverted domain notation of application/vnd.com.example.app.foo+json, which prevents namespace conflicts. If and when your media type becomes stable and public, it might be a good idea, but there's no requirement. Could be wrong on this, though.
Will you get any value by specifying a complete mimetype? Would you do anything with the complete mimetype different than you would if the mimetype was application/json?
My 2 cents- If the API is not going to be made public, then I see no reason for a complete mimetype. A mimetype of application/json should be more than enough. You already know the type of json that the response is returning. If the API eventually becomes public, then worry about a complete mimetype... or just let people figure it out.