I'd like to know if the following is possible.
Swagger is almost what I need to document a Message based API. For instance for a Command Message I'd like to say "Command" instead of "Post", and instead of "path" I'd like to have the name of the Command.
The spec mentions that Vendor Extensions are possible using "x-" properties but I am 1) not finding any examples of how to do this and 2) not sure if the use of these properties would help me meet my goals.
Might anyone be able to point me to some resources that can help me move along?
Swagger is designed to document REST APIs which are based on HTTP verbs. You can't replace verbs or invent new ones.
Vendor extensions are there to allow adding additional information that the specification does not allow, but ultimately, it is still intended for REST APIs.
From what I gather, you're trying to describe something different.
We do welcome suggestions for additional roads for Swagger (that is, cover non-REST APIs), and in order to do that, I'd suggest opening an issue on the swagger-spec repository.
Related
I am currently using fastify (3.20.1) and fastify-swagger(4.8.4). The situation is: I can add all the REST API verbs (PUT, PATCH, DELETE etc.) in my route specification in JavaScript Node Js.
Now I want to add a customized stuff like "Doc" in every section. Something like in the below:
MySection
Doc
GET
POST
I can see the fastify documentation that it supports, quite logically, the typical REST API verbs.
My question is: how can I support another 'custom verb' (like doc).
One way, naively, I can think of: to download swagger ui and add some customization there. But then how can I may register my swagger-ui to fastify.
Please suggest what is the best way to go forward.
Thanks,
Pradip
I have some questions regarding swagger-ui. I have downloaded the swagger-ui from here and have played around with the index.html and tried modifying it. From what I understand the UI is dynamically generated based on the open api specification doc either in a yaml or json file format. My questions are as follows
How much modification can be done to the UI that is being generated by the Swagger?
Can "Try Out" functionality be modified to have more control? What I want to do is have few input fields which are not generated by swagger and use them as input for an api call, make UI more dynamic in nature.
Does the Swagger-UI depend on any sort of API gateway to make calls to api endpoints?
Thanks,
Salil
How much modification can be done to the UI that is being generated by the Swagger?
Swagger UI can be tweaked in very different ways mainly via JS or CSS.
You can have a look to https://swagger.io/docs/open-source-tools/swagger-ui/customization/overview/
Can "Try Out" functionality be modified to have more control? What I want to do is have few input fields which are not generated by swagger and use them as input for an api call, make UI more dynamic in nature.
You should have a look to the link I shared above but not sure this is doable like this.
If I had to do such kind of thing I would rather look at how to complete the original OpenAPI definition (the yaml/JSON file) before passing it to Swagger UI.
Note that there is also a "interceptor" feature in Swagger UI that allow to modify requests before sending them for instance. This might interest you.
Does the Swagger-UI depend on any sort of API gateway to make calls to api endpoints?
Not at all. Swagger UI just uses your browser to call the API at the URL documented by the OpenAPI file.
Stack Overflow doesn't work well when there are multiple questions as part of one "Question". Having said that, I'll answer what I know.
As far as I can tell, you can modify the yaml or JSON source as much as you like. You can write an entire file from scratch, or import it from any editor.
For this sort of testing, I think you might want to look for a more in-depth testing tool such as Postman. That's not something I have any experience with, but from what I hear it could help with "what if I send this request?" sceanrios.
I have been given a Swagger API with a request body defined as
{
"SqlFilterList": "string",
"SubjectKey": 0,
"SubjectCwaListingKey": 0
}
The programmer who wrote the API is on vacation and can't be reached. I don't have access to the API code. Is there in general anyway to interrogate the api to determine what the valid values of "string" might be? Or do I have to wait for the person to come back to the office?
I have reviewed the API's documentation via its URL (which is why I know that it needs a string), I searched the Swagger website and I searched questions with tag [swagger] in stackoverflow and didn't spot anything.
If the answer is that I am out of luck (which I strongly suspect to be true) is there a way that I can suggest to the author to document the valid syntax of the "string" in the API so that the next person doesn't go through this?
It sounds like you have found your way to the Swagger-UI, displaying the API documentation and interactive "try it out" buttons.
Most likely, the API is just not documented as thoroughly as you need it to be. But there's a chance you might be able to find more information from the Swagger spec. A couple of things you can do to dig deeper:
Look at the Request Model
In the Swagger-UI, click the "model" tab in the operation header:
This will display additional details about the request structure, if the developer has provided property-level descriptions. The misnamed "model schema" tab that displays by default is really an auto-generated example of the message structure; not so useful if you're looking for detailed request documentation.
Inspect the Swagger Source
You might be able to inspect the Swagger source specification that is populating the Swagger-UI. Try using the "view source" command in your browser, and look for the SwaggerUi object constructor. It will look something like this:
var swaggerUi = new SwaggerUi({
url: 'http://petstore.swagger.io/v2/swagger.json',
dom_id: 'swagger-ui-container'
});
Follow the specified url to find the source Swagger spec, and see if there is any further information available. It's unlikely that you'll find more there than what's displayed in the Swagger-UI, but it's worth a shot.
Note that there's another form of the SwaggerUi constructor that doesn't use a url property. Instead, it uses a spec property whose value is a (big!) JSON object. You can copy-paste that object into a Swagger or JSON editor (for easier reading with auto-format, syntax coloring, etc.) and see if there's any further info there.
If the answer is that I am out of luck (which I strongly suspect to be true) is there a way that I can suggest to the author to document the valid syntax of the "string" in the API so that the next person doesn't go through this?
Hopefully the API developer has provided a feedback channel, either through email or a support site. There might be some API documentation widgets that incorporate feedback or discussions directly, but Swagger-UI does not at this time, AFAIK.
As you might now, Loopbackjs framework displays a swagger-based explorer interface exposing your API endpoints and briefly explaining the methods. The problem it's that this interface it a little too much interactive.
I need to provide an api-docs (ish) documentation for my API, and I'm currently adding #annotations in /common/models js files, but I suspect I'm reinventing the wheel here. For swagger-ui / loopback-explorer to display its interface, the endpoints must be already exposing some kind of metadata, right?
I'd like to get that and complete it with description, examples, custom status codes and without "try it" buttons. The users that will see this wouldn't appreciate so much interactivity.
You can access the "swagger" for your LoopBack Models by clicking the "raw" button at the far right of any Model in LoopBack Explorer and you'll see the swagger JSON that describes you Model.
If you really want to customize your API explorer interface, check out this article:
http://www.podstud.io/blog/angular-swagger-jacking/
Then you'd access the Model Swagger Resources and provide any sort of slick interface you want...
Hope this starts you in the right direction...
I'm working on a collaborative document editing application where clients can open up a document, post edits via a webservice, and subscribe to updates made to the document using SignalR. I'm experimenting with my SignalR setup and can't quite get what I want.
My gut tells me that I should shoot for a setup where each document has an endpoint with a name like "subscribe", so the full path would be "/documents/1/subscribe" for document 1 and "/documents/2/subscribe" for document 2. However, as far as I can tell, SignalR wants me to have a single endpoint, and then manage which clients get updates either by using Groups or by managing the list of subscribers for a document in code myself and send out individual messages.
As a result I have two questions.
Is there a way to do what I want to do what I want to do with SignalR?
Is there a reason what I want to do is totally wrong headed and silly?
Aside from "dedicated", friendly looking URLs I don't really see any value to this vs. just using groups. In fact, the only thing I could see it doing is adding more overhead because of the way the message bus internals of SignalR work with respect to scale.
If you did want to try this, the base thing you'd need to figure out would be registering routes on the fly per document, which, as Phil Haack's RouteMagic has done for MVC, I suppose it might be possible for SignalR route configurations as well.