Using jhipster 5.7.2
I created an api-gateway, and two micro-services.
In the first one, I created an entity and it works perfectly behind the gateway. The gateway displays the api endpoints for the generated entity.
I generated the second micro-service but this time I had already an api defined in a yml file so I chose 'API-first'.
My api was defined using open-api 3.
I successfully generated the code for my api, using the instructions there, and tested calling direcly my micro-service endpoint using curl : it worked as expected at this point.
The problem : when I put that micro-service behind the gateway, the gateway does not see the api. When I go to the api menu, my micro-service shows in the dropdown but when I select it, it shows no endpoints.
One weird thing I found while searching is that when I call the following url on my micro-service directly : http://localhost:8082/v2/api-docs (as pointed in the 'welcome page' of the micro-service), I get :
{"swagger":"2.0","info":{"description":"my micro-service API documentation","version":"0.0.1","title":"api-first micro-service API","contact":{},"license":{}},"host":"localhost:8082","basePath":"/"}
It says 'swagger 2.0' when my yml file declared openapi 3.0.1.
I searched and found this issue, which says :
Swagger UI very old version (2.2.10) is used which does not provide
the support for Open API
I though openapi was the problem, so I rewrote the yml file to swagger 2.0 and finally I have the same exact problem : micro-service API works but seems not visible to the gateway.
I'm starting to wonder if it's a problem on my side only.
By default, JHipster configures Swagger to only list API endpoints beginning with api. This is configured in application.yml, change default-include-pattern to include other paths. For example, to include endpoints beginning with either /api/ or /expires/, you can use the following:
swagger:
default-include-pattern: /(api|expires)/.*
Related
I’m trying to use an OpenAPI file into GitLab (which runs the UI for my file) but when I use the feature Try Out/Execute from Swagger UI (which sends a request to an external API) I get an error with Content Security Privacy.
My OpenAPI works on Swagger Editor online, and in Gitlab don’t. I think that I need to set this external URL but I have no idea where to do it. Maybe something in my OpenAPI code? Or a setting in GitLab?
The error:
Just change a file name to:
openapi.yaml
I'm working with a fairly complex NodeJS API that has been written using hapiJS.
The API uses the hapi-swagger npm module to generate the API documentation.
I'm now investigating how to integrate the Amazon API Gateway with this API, in order to provide the authentication/request throttling etc.
To create an Amazon Gateway API, it appears that I need to provide a Swagger definition.
My question is, how do I generate this swagger definition? I'm assuming there must be some way to do this automatically from hapi-swagger, but I haven't been able to find it.
If you are using hapi-swagger the default endpoint that returns the swagger.json is /swagger.json.
See https://github.com/glennjones/hapi-swagger/blob/c02dd0dc8632766006854d1a4ddcd88a77a411c8/optionsreference.md#json-json-endpoint-needed-to-create-ui --> jsonPath
I am trying to import an API I have into Azure API Management using swagger, should be fairly simple but I always get the same error:
One or more fields contain incorrect values: API with specified name
already exists
I do not have ANYTHING setup in Azure API management yet, very frustrating.
UPDATE
I am using Swashbuckle (https://github.com/domaindrivendev/Swashbuckle) to add Swagger to my WebAPI project.
It is generating Swagger 2.0 docs.
Here is the info element of the Swagger Doc:
swagger: "2.0",
info: {
version: "v3",
title: "ShopZioAPIv3"
},
It does not matter what I change that to, I still always get:
One or more fields contain incorrect values: API with specified name
already exists
I my case the title {"info":{"title": "API-NAME",... in the Swagger file did not match the name of the selected API (because we had created several test APIs).
Simply changing the string value fixed it.
That error message appears when you don't specify a unique API prefix.
I realize that you said that you don't have anything already already setup in the API however, if you could try putting some unique value in this field:
An API Management service instance is designed to host multiple APIs, so the prefix is used to differentiate between the APIs by using the first part of the path.
The subdomain part of the URL is used to identify the service. e.g.
http://{servicename}.azure-api.net{/api-prefix}/path/segment?param=value
Update
Based on the provided Swagger, the problem comes from multiple operation objects with the same OperationId. This is invalid swagger.
Usually Swashbuckle will fail before generating operations with duplicate Ids. There is a ResolveConflictingActions method that allow you to put your own code to deal with these cases. It seems like in this case the resolution code is not doing the right thing.
The Azure API Management error, "API with specified name already exists," can be misleading, and in this case, it is inaccurate.
As discussed in Darrel Miller's answer, invalid Swagger can cause this issue. Although multiple operation objects with the same OperationId is invalid in Swagger 2.0, I think the core issue you are having is that Azure API Management does not yet support Swagger 2.0 (as of Dec 1, 2015).
Swashbuckle 5+ generates only Swagger 2.0 so some,if not all, definitions generated with it will fail with this error -- even well-formed Swagger definitions validated by http://editor.swagger.io, which also seems to only support Swagger 2.0.
Swashbuckle 4.2 supports generating Swagger 1.2 definitions.
Also, I was able to take my Swagger 2.0 definition (generated by Swashbuckle 5), and convert it to Swagger 1.2 using Restlet Studio.
I'm migrating a combined Azure Website (with both Controllers and ApiControllers) to a split Web App and API App. Let's call it MyApp.
I've created MyAppDevApi, MyAppTestApi, and MyAppProductionApi API Apps (in different App Services) to host the three environments, expecting to promote code from one environment to another.
So far, I've only deployed to MyAppDevApi, since I'm just getting started.
When I do Add/Azure API App Client to my UI-only project to start referring to the API app, and I point it to MyAppDevApi, it uses AutoRest to create classes in my code. These classes now all have the name MyAppDevApi, rather than just MyAppApi, which is the actual namespace of the code I'm deploying to every environment. Obviously, I can't check that in... how can I promote that through Test and Prod?
There's nothing in the Swagger JSON that refers to this name, so it must be on the AutoRest side (I think).
Has anyone come up with a strategy or work-around to deal with this multiple-environment promotion issue with API Apps?
Edit
So far the best thing I've come up with is to download the Swagger from the API App to a local file (which, again, has only the namespace from the original code, not from the name of the API App), and then import it into the Web App. This will generate classes in the Web App that have the naming I expect.
The problem is that I then have to edit the generated MyAppApi.cs file's _baseUri property to pull from an AppSetting, have the different web.config.dev, .test, .prod, and then do the web.config transform. I mean, that'll work, but then every time I change the API App's interface, I'll regenerate... and then I'll have remember to change the _baseUri again... and someone, sometime is going to forget to do this and then deploy to production. It's really, really fragile.
So... anyone have a better idea?
I'm not quite sure why you're creating three different apps, one for each environment? One application is fine and use web.config transforms for each environment. This is the general way I do all of my apps and works fine.
Information about how to apply web.config transforms can be found here which may help in your situation.
Hope that helps.
Well, here's how I've solved this:
Download Swagger file from API App to local hard drive.
Import local Swagger file into Web App to generate classes that have the naming from my code, not from the environment.
Use AppSettings to specify the environment-specific settings to point to the API App. This can be either a web.config transform, or you can just specify them in the Azure Portal on the Web App in Application Settings.
Instantiate the generated API App Client using the constructor that takes in a URL to point to the API App (these are at class level, hence static):
private readonly static Uri apiAppUrl = new Uri(CloudConfigurationManager.GetSetting("ApiAppUrl"));
private readonly static MyAppApi myAppApi = new MyAppApi(apiAppUrl);
I'd still love a solution to this that doesn't require downloading the Swagger file, but, all in all, if that's the only workaround necessary, it's not all that bad.
I have a few private apis written in plain old express. Time to let it out and provide some api documentation.
What I don't want (at least yet) it to re-write my express app to integrate api documentation into the code. Mainly since I am not sure what framework or spec to use to document my api I don't really want to be locking into one particular thing.
I would like to serve out the doc as part of a sub resource under my api (ie I do not want to run a different server or subdomain). Maybe '/api/docs'. A plus would also be a UI that I could embed within my app that could parse the docs and at the very least provide a nice presentation of the docs in html (api interaction is a plus).
Things like swagger-node are cool, but would require me to re-write all my express code to integrate swagger. At that point I have a big investment and am tightly coupled to swagger.
Is there a way to serve out swagger or iodocs or maybe something else to document my api in a way that is minimally invasive to existing routes?
EDIT:
I could serve out the Swagger spec from a hand written doc. Problem I see is that you have to define basePath in the swagger doc. This does not really allow me to easily deploy under different domains.
There's a wide array of node.js tools to integrate Swagger with your application, and I assume they offer different ways of doing so. You can find a list of such integrations here - https://github.com/webron/swagger-spec/#nodejs - but I can tell you that there are additional tools out there that are not listed there. You can try searching github for swagger and node/express.
As for the manual spec and the basePath - Swagger 2.0 actually solves that for you. You can use the online editor - http://editor.swagger.io - to write your specs in a more human-friendly YAML form, which then you can export to JSON.
Unlike Swagger 1.2 and previous versions, the basePath is now split into three properties - schemes (http, https), host (domain, port) and basePath (the root context of the application). None of these properties are mandatory, and they all default to whatever is serving the swagger.json file (the spec itself). schemes defaults to the scheme service the swagger.json, host defaults to the host used for serving the swagger.json and basePath will be \ unless explicitly specified. I believe this should solve your concerns regarding the basePath.