I'm documenting a list of APIs using OpenAPI 3.0 and a separate YAML file for each API.
All APIs use the same target server, so currently I have the following in each API definition:
...
servers:
- url: www.abc.com
description: "Production Server"
But I don't want to repeat the servers in all API definitions. Instead, I would like to reference the servers from a single file, like so:
# sample.yaml
...
servers:
$ref: 'index.yaml#/servers'
But Swagger UI shows the "Could not render this component" error.
Is it possible to $ref the servers in OpenAPI 3.0 definitions?
OpenAPI 3.0 and 3.1 Specifications do not support $ref in servers.
Here's an existing feature request:
https://github.com/OAI/OpenAPI-Specification/issues/2338
Related
I am quite new in the orocommerce ecosystem, and I would like to generate API client librairies automatically for orocommerce API (frontend and backend). The objective is to build my own UI.
I found some dependencies on NelmioApiDocBundle than could potentially generate swagger file, but I hit multiple problems:
this is a quite old version, that only support swagger 1.2
the generated file (using symfony run php bin/console api:swagger:dump /tmp/api/) seems not working with swagger codegen "as is"
all the part of the API seems not written using NelmioApiDocBundle annotation
I am wondering if there is an other mechanism to generate API client librairies for orocommerce. I would like a SDK for typescript.
Thanks in advance for your answer.
Right now, the only supported swagger version is 1.2, as you stated.
By default, the api:swagger:dump command works with an outdated API, to generate data for the current API, run it with --view=rest_json_api option:
api:swagger:dump --view=rest_json_api
As an alternative to the API client generation, as Oro API strictly follows JSON.API standard, you can use many existing client libraries, compatible with the JSON.API specification. The list of Typescript implementations can be found at the official website: https://jsonapi.org/implementations/#client-libraries-typescript
I have backend system in Web API using asp.net core where I am using Swashbuckle.AspNetCore package for generating OpenAPI Specification document. The OpenAPI specification document is generating fine something like '~/swagger.json'. I hookup this url in APIM via OpenAPI specification it works like a charm.
However if the '~/swagger.json' gets updated due to adding new operation,documentation and so on. The changes are not getting reflected in APIM. How can I solve this problem?
If APIM is not able to detect the changes automatically then can I mention the url '~/swagger.json' in ARM template something like that and while doing complete deployment of the APIM for e.g.in other or higher environment the spec gets reflected there. I also tried to download the ARM template from portal I was not able to see a place where I can specify '~/swagger.json' url.
There is option from UI to import spec again but any easy automated way of doing this would be appreciated
Ues PUT /apis/... call in Azure APIM rest API and specify below as payload:
{
"properties": {
"format": "swagger-link-json",
"value": "https://contoso.com/swagger.json"
}
}
Docs: https://learn.microsoft.com/en-us/rest/api/apimanagement/2019-12-01/apis/createorupdate#contentformat
As the krakend.json is not of the type which swagger understands.Following error occurs:
Error: Document must be valid OpenAPI 3.0.0 definition
Is there any alternate way to generate documentation for krakenD
Generating both KrakenD configuration and OpenAPI documentation is possible, but...
You should precisely define your use case:
Do you want to generate krakend.json config from OpenAPI just as no-op proxy? (see an example script)
Are you willing to adopt another (custom) format? (see openapi2krakend)
Do you want to generate OpenAPI documentation from KrakenD config? If so, do you need just a list of endpoints or do you want also to have defined descriptions, examples and types (!) in one file?
You should (at least try to) write the script to generate the configuration by yourself to suit your needs.
Consider a usage of KrakenD Studio that has the OpenAPI generator plugin.
It can look like a good idea, but the devil is in the details and you should analyse your requirements because these two files have totally different purposes. I can only suggest you write such a transformation script (as I did) which should be like "5 minutes of work" and then go to the deep.
Edit: We have selected a subset of KrakendD features and implemented our own configuration generator (from OAS). We use tags with a custom route-to/ prefix for metadata, a definition could look like this:
/coupons/{id}:
get:
tags:
- Coupons
- route-to/path=/coupons/{id}/detail
- route-to/backend=GET|http://coupons.content
- route-to/flags=jwt_validation
I want to use the specification in to generate a Java client using swagger codegen in order to consume the REST API from a Java application. Where do I find the Open API spec after I start the composer-rest-server? I've tried looking it up but I can't figure out where that file is stored after it is generated.
By default, the docs are at your localhost:3000/explorer
This is generated automatically by the LoopBack framework.
You should carefully follow: https://hyperledger.github.io/composer/integrating/getting-started-rest-api.html
i'm trying to use swagger-codegen-maven-plugin to generate my interface .
after compiling with the plugin - it generates all the files correctly but for some reason
the interface name is DefaultApi.
i looked for some configuration that i can change the name of the interface that been generated but didnt find the solution for that.
any idea on that??
"DefaultApi" is used when there's no tags specified for the endpoint.
For example, this endpoint will be put in a class named "UserApi" since the tags is set to User.
You will need to update the spec to include proper tags for endpoints to avoid using "DefaultApi"
UPDATE: On May 2018, about 50 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen to maintain a community-driven version called OpenAPI Generator. Please refer to the Q&A for more information.