In OpenAPI 3, what changes would I have to make in the yaml so that the dropdown of Servers in the swagger yaml is instead a text box where devs can put in their own ApiPaths for testing their own deployments.
So the Server Templating section in https://swagger.io/docs/specification/api-host-and-base-path/ does just this.
servers:
- url: https://{customerId}.saas-app.com:{port}/v2
variables:
customerId:
default: demo
description: Customer ID assigned by the service provider
port:
enum:
- '443'
- '8443'
default: '443'
In this case customerId will show up as a text box in the swagger.
Related
Swagger-parser version: 2.1.1
Example swagger spec:
The test case is quite large, so I put it in a github gist. Don't be surprised by the names of the paths and schemes - I masked the critical data.
Description:
When using the ResolveFully option, I get requests with unresolved links. For example, take the request POST /v1/BusinePEH0JF. In swagger-ui it renders correctly - in the request body in the manager field, the Emplo4XN6X schema is resolved:
enter image description here
But swagger-parser gives this result:
enter image description here
Here the link is not resolved. This is most likely due to the fact that the parent schema BusinesYD77B4X in this request is stored as such in resolvedModels due to the fact that it is also used in other requests, such as POST /v1/ApprovalSetU0C9RY71SHD/manager-to-employees. Here, the manager field is empty, because this scheme has already been used above in the approver field.
enter image description here
Reproduction of the error:
val parseOptions = new ParseOptions()
parseOptions.setResolve(true)
parseOptions.setResolveFully(true)
val openAPI = new OpenAPIV3Parser().read(swaggerSpec, null, parseOptions)
Expected result:
Like on the first screen in swagger-ui
Thanks!
I have a java spring boot service mesh of services.
I am using open api for swagger documentation.
When I run my spring cloud gateway and access http://localhost:{my-port}/swagger-ui.html, it works fine and loads the swagger ui which mentions /v3/api-docs in the "Explore" title bar.
Also, when I add the service name to the url like so /v3/api-docs/my-service, it works fine.
However, I want to try a list of dropdown services instead of manually appending the service name for each service. I have tried this grouping code in my gateway:
#Bean
fun apis(): List<GroupedOpenApi> {
val groups = ArrayList<GroupedOpenApi>()
val definitions = locator!!.routeDefinitions.collectList().block()
definitions!!.stream().filter { routeDefinition -> routeDefinition.id.matches(".*-service".toRegex()) }.forEach { routeDefinition ->
val name = routeDefinition.id.replace("-service".toRegex(), "")
GroupedOpenApi.builder().pathsToMatch("/$name/**").setGroup(name).build()
}
return groups
}
Now, after this when I access http://localhost:{my-port}/swagger-ui.html, it shows a drop down list of all the service with the "-service" removed. But after selection, the docs don't show up.
Although, if I access it in a separate tab with http://localhost:{my-port}/v3/api-docs/my-service, it shows me the json of all the paths and works fine. Just doesn't load in the swagger ui.
Here's gateway route for one of the service and openapi:
- id: my-service
uri: lb://my-service
predicates:
- Path=/api/v1/my/**
filters:
- name: CircuitBreaker
args:
name: my-service
fallbackuri: forward:/myServiceFallBack
I want to configure passwords in the config map.YAML instead of deployment.yaml.able to set username and other variables.attcahing the config map.YAML file which I worked on.
kind: ConfigMap
apiVersion: v1
metadata:
name: poc-configmapconfiguration-configmap
data:
Environment: [[.Environment]]
dockerRegistryUrl: [[.Env.dockerRegistryUrl]]
CassandraSettings__CassandraPassword:
valueFrom:
secretKeyRef:
name: abcd-passwords
key: "[[ .Environment ]]-abcd-cassandra-password
As already suggested its better practice to use secrets to store passwords
Secrets obscure your data using a Base64 encoding so it is good practice to use Secrets for confidential data over using ConfigMaps.
If you perform a explain on ConfigMap field to get more details from CLI it self on the ConfigMap.data it accepts map of strings.
$ kubectl explain ConfigMap.data
KIND: ConfigMap
VERSION: v1
FIELD: data <map[string]string>
DESCRIPTION:
Data contains the configuration data. Each key must consist of alphanumeric
characters, '-', '_' or '.'. Values with non-UTF-8 byte sequences must use
the BinaryData field. The keys stored in Data must not overlap with the
keys in the BinaryData field, this is enforced during validation process.
So above yaml structure you used should throw a error on creation time something like below ..
invalid type for io.k8s.api.core.v1.ConfigMap.data
Refer this git request for such feature request , which is already closed with no support considered.
https://github.com/kubernetes/kubernetes/issues/79224
It would be more common to use a Secret, as you can see from the secretKeyRef, however an equivalent configMapRef exists and be used in the same way.
from the site docs: swagger.io/docs/specification/api-host-and-base-path/
you can create variable arguments for parts of the server URL, but when I try the below configuration from the page on my site and pestore (), the selected server URL shows up as: "https://{region}.api.cognitive.microsoft.com",
I want it to show up with the default filled in like:
https://westus.api.cognitive.microsoft.com
- url: https://{region}.api.cognitive.microsoft.com
variables:
region:
default: westus
enum:
- westus
- eastus2
- westcentralus
- westeurope
- southeastasia
I have web app that i deploy for multiple clients (lets say client1.com, client2.com and client3.com). I wrote REST API documentation using OA3 specification.
I have index.yaml which looks like:
openapi: 3.0.0
info:
title: REST API
description: REST API
version: 0.0.1
servers:
- url: http://client1.com/api
description: Something ...
tags: ...
and standard Swagger-ui index.html
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "docs/index.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset.slice(1)
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
});
// End Swagger UI call region
window.ui = ui;
My problem is that i need to change servers.url depending on where and for which client i deploy app, so that each client can test API on his own servers and i don't want clients to see each other and know about each other in REST API docs.
How can i "dynamically" change / set server.url ? One "walkaround" solution is to copy index.yaml for each client and hardcode servers.url, but im sure there is better way which i don't see / know about.
Edit #1: given duplicate answer does not help because when i set servers to
servers:
- url: /api
swagger ui still points to http://localhost:8080/api/ but my app url is http://localhost:8080/myapp/. I could set servers: - url: /myapp/api but this is hardcoded value in index.yaml and that does not work for me. I need like "configurable" server url.
But thanks anyway
Edit #2: my current walkaround solution is to process yaml with server side code. In index.yaml i have:
servers:
- url: ##INSERT_SERVERS_TAG_HEREapi
and i replace ##INSERT_SERVERS_TAG_HERE with myapp.client.com/. But i'm still looking for some better solution.