I've just installed WSO2 2.0.0 (as far as I know, this is the version following v1.9.0, not a breaking compatibility version). I'm using it via Firefox 40.0.2 on Windows.
When I try to add a new API via "I have an existing API" menu, whatever I do, it always open an empty design API screen : https://localhost:9443/publisher/design
In this screen, when I try to import an API (swagger file or swagger URL), it just does nothing without prompting any error. My swagger file respects Swagger API 2.0 spec and corresponds to an API already used in production.
What should I do to get at least a useful error message regarding this API import ? (if it's installing an other version of WSO2, it's a valid answer for me.).
Here is the Swagger file I try to import :
{
"apiVersion":"2.0",
"swaggerVersion":"1.2",
"basePath":"/ValoConso/rest",
"resourcePath":"/valoConsoWebService",
"apis":[
{
"path":"/valoConsoElec",
"operations":[
{
"method":"POST",
(...)
}
]
}
],
"models":{
(...)
}
}
It seems the swagger document you are trying to import is of swagger version 1.2 ("swaggerVersion":"1.2"). From API Manager 1.9 onwards we should use swagger 2.0 compatible definitions.
You can use http://editor.swagger.io/#/ to validate your swagger definition according to 2.0 specification. Please try converting it according to 2.0 specification and then import to API Manager 2.0.
See some useful resources:
[1] Swagger 2.0 samples : https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json
[2] Swagger 1.2 -> 2.0 migration guide: https://github.com/OAI/OpenAPI-Specification/wiki/swagger-1.2-to-2.0-migration-guide
Related
I cannot get Postman to recognize https://chat.googleapis.com/$discovery/rest?version=v1
I normally import Swagger documents and it creates collections for me without any problems. But this is not a Swagger file, it's a Google "discovery document". I would have thought that Postman would somehow recognize this Google format but it doesn't. Is says: "Error while importing: format not recognized...".
My question: Without adding all methods separately, how do I "consume" / import this API in a / as a Postman collection?
I've not used it but you could try the Google Discovery to OpenAPI 3.x Converter, which converts Google discovery documents to OpenAPI (Swagger) format.
I have similar question as in this questions Default version for API Management
However the question is old, had there been any recent changes in APIM which allows this behaviour where if you dont pass any versions in header/path/query it routes to latest versions
/api/operation?api-version=1.0 <- Goes to 1.0
/api/operation?api-version=1.1 <- Goes to 1.1
/api/operation <- Goes to 1.1 (Here 1.1. is the latest and if no version is pass in URI it should route to latest one(1.1 in this case))
In my case we are using Azure Function for backend API.
Just to add I am not able to comment on existing question :(
Still the same behavior, you have to provide the Api version. When you add a version to a non-versioned API, an Original version will be automatically created and will respond on the default URL so if you do not provide an Api version the original version will respond to that call.
I am trying to introduce URL versioning into my .Net Core WebAPI application. I am also using Swagger web tools for ease of use for users.
Now, while trying to introduce versioning into my application, I referenced the docs here: https://github.com/Microsoft/aspnet-api-versioning/wiki/New-Services-Quick-Start#aspnet-core
Now, I made following code changes into my code:
Startup.cs/ConfigureServices I added code below:
services.AddApiVersioning(options => {
options.AssumeDefaultVersionWhenUnspecified = true;
});
Now, my controller annotations before any kind of versioning was added, looked like below:
[Produces("application/json")]
[Route("api/controllerName")]
and produces a URL which looks like something below:
http://localhost:12003/swagger/#!/Workspace/GetAll
Now, I added annotations below to enable api versioning:
. [ApiVersion("1.0")]
[Produces("application/json")]
[Route("api/v{version:apiVersion}/workspace")]
and now when I click on the same method listed in my swagger UI
the url looks like below:
http://localhost:12003/swagger/#!/controllername/ApiV_versionGetAll
While what I was expecting was something like:
http://localhost:12003/swagger/#!/controllername/V1.0/GetAll
Also on my swagger it is now asking me explicitly about entering version number. So I think my question boils down to two major points:
How I can I fix my URL? and what am I doing wrong?
Why is swagger now asking me to enter version number in API UI when I have explicitly stated that the version is going to be 1.0 in the annotation of the controller?
What you are missing is the complementary package for API versioning that supports an API version-aware API Explorer:
https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
The API Explorer is how Swagger generators like Swashbuckle do all their work. The source and links are also available in the API versioning repo.
To achieve the result you want, you need to configure API version substitution in the URL:
services.AddMvcCore().AddVersionedApiExplorer( options => options.SubstituteApiVersionInUrl = true );
Note: that the call the AddMvcCore() is no longer required in API Versioning 3.0+
Documentation and samples are available in the official API versioning repo. I recommend reviewing the API Documentation wiki topic:
https://github.com/Microsoft/aspnet-api-versioning/wiki/API-Documentation
The accepted answer extends this package, which is fine as long as it stay up-to-date with the flavor of API versioning you are using. API Versioning always ships compatible API Explorer extensions on every release.
Setting up api versioning with swagger is indeed a tricky thing as it is lot's of pieces that need to be setup correctly.
Luckily for us, there's a great nuget packages called SwashbuckleAspNetVersioningShim which solves this in an excellent way.
Add it
Install-Package SwashbuckleAspNetVersioningShim -Version 2.2.1
Then follow the readme here
Is there any spec or convention on URL where one should place swagger.json (or whatever name it is agreed) so that public API of my site can be automatically discovered?
Updated 19 April 2017: The OpenAPI Wiki answer I gave previously is "for a very very very old version of the spec". The same source states that for 2.0 the standard is swagger.json, for 3.0 it changes to openapi.json.
Original answer:
The OpenAPI Wiki recommends using an /api-docs endpoint, at
least for server APIs. I've seen several sites in the wild that use
that, and it's our shop standard.
Hope that helps.
How about serving the Swagger JSON in an HTTP response body, in response to an OPTIONS request for the URL / ?
This is specifically permitted by the relevant RFC.
Further, consider implementing HATEOAS, as strongly advocated by Roy Fielding.
Okay. OpenAPI 3.0 still lacking auto-discovery mechanism, I try to propose a scheme based on some things that were already working:
https://example.com/.well-known/schema-discovery is a JSON document pointing to array of available schemas:
[
{
"schema_url": "/openapi.json",
"schema_type": "openapi-3.0"
},
{
"schema_url": "/v2/openapi.json",
"schema_type": "openapi-3.0"
}
]
If there is only one version of API, then https://example.com/openapi.json should be enough.
HTTP Headers. I remember somebody from Google proposed HTTP header for pointing to API. If you can find or remember it, please tell me.
UPDATED QUESTION to clarify more.
I have two servers : wso2greg containing custom artefacts and wso2am (api manager).
The gouvernance register is intended to be used internally (intranet) and some of it's feature are intended to be exposed externally and acceded via it's rest API.
In order to manage wso2greg API accesss, we used an wso2am (api manager) server, where we did define an API that act as a proxy for the wso2greg API.
In our experiments, we found the strange behaviour described below :
Successfully direct calling wso2greg artefact rest api (the exact url is
https://localhost:9443/resource/1.0.0/artifact/_system/governance/myartifact/art1 and i'm following the documentation of this REST API from here https://docs.wso2.com/display/Governance520/Resources+with+REST+API ) using postman. The API reacts as described in the documentation.
Error 500, reported on wso2greg server, when calling the same REST API, but via API manager (using publisher application).
So as a summary :
Directly calling wso2greg rest API woks fine and a got results back
Adding this working API, in wso2am and than calling it gives always error 500.
As extra information:
Tested with other wso2greg REST API , such as "rating" or "comments" and I was able to call it successfully either directly or throw Api manager.
Tried to get information related to default wso2greg artifacts such as restservice, but i got exactly the same pb when (error 500) interagting with API manager.
Working with the last version of both products : wso2greg version 5.2.0 and wso2am version 1.10.0
Please advice, or clarify how could i debug this internal error in wso2greg.
Regards,
I hope your not using G-Reg + APIM feature installed version. I presume your using separate G-reg 5.2.0 and APIM x.x.x. Since your using the second option you can't use G-Reg REST API with APIM, therefore you have to use APIM REST API instead.
Get an API
Description: Get details of a specific API.
URI: http://localhost:9763/publisher/site/blocks/listing/ajax/item-list.jag
URI Parameters: action=getAPI&name=xxx&version=xxx&provider=xxx
HTTP Methods: POST
Example:
curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/listing/ajax/item-list.jag -d "action=getAPI&name=PhoneVerification&version=1.0.0&provider=admin"
Please follow this link to see all the api usage.
Thanks #thusharaK for providing help.
The solution was to add Message Mediation Policies which forces json header on output.
Now i got my correct response from API manager (in fact, i got a binary response in test console and a json response in postman) .