I have a collection of microservices, each with their own complete OpenAPI spec and a root level path
Microservice Definition
openapi: 3.0.0
info:
description: Microservice API
version: '0.0.1'
paths:
/:
get:
tags:
- Root
summary: Root Path
operationId: Root
responses:
'200':
description: Request was successful
deprecated: false
/healthcheck/ping:
get:
tags:
- Healthcheck
summary: Test the reachability of the microservice.
operationId: Ping
responses:
'200':
description: Request was successful
deprecated: false
And a root OpenAPI definition
openapi: "3.0.0"
info:
version: 1.0.0
title: API
servers:
- url: http://api.something.com/v1
paths:
/microservice1:
$ref: "https://storagebucket.someservice.com/service-definitions/microservice-swagger.yaml"
It's been my assumption that it's possible to arrange things this way but I'm getting a whole host of errors in the swagger editor for validity.
Using microservice-swagger.yaml#/paths/~1 gets me somewhere but I would expect that all the paths in the service yaml to simply be appended to the path in the main definition. Does anyone know how to achieve this?
(The reason behind it being to apply this root swagger to an API Gateway whilst maintaining each service as a self contained unit)
I would for example expect the resulting swagger to offer this as a path
/microservice1/healthcheck/ping
Related
Super basic (video) but the title is nearly my comment to Top 3 ways to run your containers on Google Cloud
User Authentication (content) in 2020 about api gateway from endpoints
Maybe a focal point for an answer could be the app engine role for api gateway in 2022. swagger.yaml (#comment)
# openapi2-run.yaml
swagger: "2.0"
info: # >1 API/service; spec x-google-api-name OpenAPI document extension.
title: backbank # mastercard-backbank # API_ID optional-string
#https://cloud.google.com/api-gateway/docs/get-started-cloud-run
description: node cloud run api mastercard p.12 customer keys # Sample API on API Gateway with a Cloud Run backend
version: 0.0.1
security:
- firebase: []
securityDefinitions: #https://cloud.google.com/api-gateway/docs/authenticating-users-firebase
firebase: #bearer https://cloud.google.com/endpoints/docs/openapi/openapi-extensions
authorizationUrl: "" # empty for firebase frm bearer Authorization?
flow: "implicit"
type: "oauth2"
x-google-issuer: "https://securetoken.google.com/vaumoney"
x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken#system.gserviceaccount.com"
x-google-audiences: "vaumoney"
host: "vault-co.in"
basePath: "/" # https://stackoverflow.com/questions/71258737/making-a-cloud-firestore-rest-api-call-through-cloud-endpoints
#When the basePath property is configured in the service configuration as well,
#this header applies only to URL paths that are prefixed by the basePath property value.
#URLs that aren't part of the basePath aren't passed through regardless of the x-google-allow property.
schemes:
- https
consumes:
- application/json
produces:
- application/json
#x-google-allow:
#all
#jwt_audience: https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken#system.gserviceaccount.com/vaumoney
#x-google-endpoints:
#- name: "vault-co.in"
#allowCors: True
paths:
/:
get:
summary: Yes Hello cloud run (api gateway, load balance) service
operationId: get
x-google-backend:
address: https://vault-co.in:8080 # APP_URL endpoint(s)
protocol: h2
responses:
200:
description: This is a (Non-Graphical) Application Programming Interface
#schema:
#type: string
#default: '''ello guv'''
default:
description: Something is wrong
#schema:
#type: string
#default: '''some not 200'''
options:
summary: Enable CORS with headers
operationId: options
x-google-backend:
address: https://vault-co.in:8080 # APP_URL endpoint(s)
jwt_audience: https://vault-co.in
protocol: h2
description: |
Origin, Methods and Headers allowing headers potentially requested
tags:
- CORS
responses:
200:
description: OPTIONS responding headers
headers:
Access-Control-Allow-Origin:
type: string
#$ref: '#/definitions/String'
default: "'i7l8qe.csb.app'"
Access-Control-Allow-Methods:
type: string
default: "'GET,POST'"
Access-Control-Allow-Headers:
type: string
default: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
403:
description: OPTIONS responding headers
headers:
Access-Control-Allow-Origin:
type: string
default: "'i7l8qe.csb.app'" # '''vau.money'''
Access-Control-Allow-Methods:
type: string
default: "'GET,POST'"
Access-Control-Allow-Headers:
type: string
default: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
#content: {}
default:
description: Something is wrong
#type: string
#default: '''some not 200'''
post:
summary: Respond properly indeed
operationId: posted
x-google-backend:
address: https://vault-co.in:8080 # APP_URL endpoint(s)
jwt_audience: https://vault-co.in
protocol: h2
description: |
Successful api fetch
parameters:
- name: pageOffset
in: body
required: true
schema:
type: object
properties:
pageOffset:
description: pageOffset is required, try 0
type: string
pageLength:
description: pageLength is required, try 10
type: string
postalCode:
description: postalCode is required, try 11101
type: string
responses: # https://swagger.io/docs/specification/describing-responses/
default: #200
description: post result
#content:v3 application/json:
schema:
type: object
description: response ok
required:
- results
properties:
results:
#collectionFormat: csv
type: array
default: []
items:
type: string
meta:
type: object
properties:
title:
type: string
description:
type: string
I repeat attempts in seriatim:
gcloud api-gateway gateways delete backbank --location=us-central1
gcloud api-gateway api-configs delete backbank --api=backbank
gcloud api-gateway api-configs create backbank --api=backbank --openapi-spec=swagger.yaml --project=vaumoney --backend-auth-service-account=vaumoney#appspot.gserviceaccount.com
(a) gcloud endpoints services deploy swagger.yaml --project=vaumoney
(b) gcloud services enable vault-co.in (Principal-role permission name: "firebase-adminsdk")
gcloud run deploy backbank \
--image="gcr.io/vaumoney/endpoints-runtime-serverless:2.38.0-vault-co.in-2022-09-08r2" \
--set-env-vars ESPv2_ARGS=^++^--cors_preset=cors_with_regex++--cors_allow_origin_regex=^https:[/][/]i7l8qe.csb.app$++--cors_allow_methods=GET,POST,OPTIONS++--cors_allow_headers=Origin,Content-Type,Authorization,Referrer-Policy++--cors_allow_credentials \
--platform managed --project vaumoney
Of course, I incessantly get this:
The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header. Read more at https://cloud.google.com/run/docs/securing/authenticating Additional troubleshooting documentation can be found at: https://cloud.google.com/run/docs/troubleshooting#unauthorized-client
But OPTIONS might be the problem (albeit "" on GET):
"This would be really useful for us, we're using cloud run for all our microservices and want to call these from a SPA via API Gateway." "We're back to Cloud Endpoints and ESPv2 for the time being, but we 100% see the benefits of the managed API Gateway, should CORS support be available for gRPC requests."
What am I to do?
I am using Swagger 2.0.
Facing the error on UI as:
{"messages":["attribute responses.responses.bad$ref is not of type object"],"schemaValidationMessages":[{"level":"error","domain":"validation","keyword":"oneOf","message":"instance failed to match exactly one schema (matched 0 out of 2)","schema":{"loadingURI":"http://swagger.io/v2/schema.json#","pointer":"/definitions/parameter"},"instance":{"pointer":"/parameters/bad$ref"}}]}
It's a YAML based documentation with the following file referencing in the main swagger.yaml.
swagger: '2.0'
info:
$ref: ./info/index.yaml
host: example.net
basePath: /api/v1
tags:
- name: Name
description: description
schemes:
- http
- https
produces:
- application/json
consumes:
- application/json
parameters:
$ref: ./parameters/index.yaml
responses:
$ref: ./responses/index.yaml
paths:
$ref: ./paths/index.yaml
definitions:
$ref: ./definitions/index.yaml
externalDocs:
description: Find out more about Swagger
url: 'http://swagger.io'
Folder structure:
The parameters/index.yaml and responses/index.xml files are empty. This works perfectly in the Swagger Editor.
I am struggling to find a way to configure the BASE_PATH.
I want to configure the base path server side
I am using open-api-generator to generate subs from a swagger endpoint (asp core web api)
Is there a way to configure different BASE_PATH.
How you define the base URL is specific to the version of OpenAPI Specification you target.
Swagger/OpenAPI 2.0
Define a host at the root of your document. For example:
swagger: "2.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
host: petstore.swagger.io
basePath: /v1
schemes:
- http
consumes:
- application/json
produces:
- application/json
paths:
/pets:
…
OpenAPI 3.x
Define a URL in servers at the root of your document. For example:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets:
…
Say my OpenAPI definition has two servers. Both share the same variables. Thus I want to reference these variables to prevent duplicate code.
Actually I split my OpenAPI into files and combine it with swagger-cli bundle.
This is what it creates:
openapi: 3.0.2
info:
title: My API
description: 'some description'
version: 1.0.0
servers:
- url: 'https://stage-api.domain.com/foo/{v1}/{v2}/{v3}'
description: Staging API server for QA
variables:
v1:
description: 'variable 1'
default: 'something'
enum:
- 'foo1'
- 'foo2'
v2:
description: 'variable 2'
default: 'something'
enum:
- 'foo1'
- 'foo2'
v3:
description: 'variable 3'
default: 'something'
enum:
- 'foo1'
- 'foo2'
- url: 'https://api.domain.com/foo/{v1}/{v2}/{v3}'
description: PRODUCTION API server
variables:
region:
$ref: '#/servers/0/variables/v1'
brand:
$ref: '#/servers/0/variables/v2'
locale:
$ref: '#/servers/0/variables/v3'
paths: {}
Trying to validate this in Swagger Editor I get the following error:
Structural error at servers.1.variables.v1 should NOT have
additional properties additionalProperty: $ref Jump to line xx
Structural error at servers.1.variables.v1 should have required
property 'default' missingProperty: default Jump to line xx
Is it possible to reference the server variables or reuse them in another way?
Of course I could run swagger-cli bundle -r but I would want to prevent using that.
No, this is not supported. You can request changes to the OpenAPI Specification at
https://github.com/OAI/OpenAPI-Specification/issues
In your example, the server paths are almost the same except for the subdomain, so you can use a single server definition and make the subdomain a variable:
servers:
- url: 'https://{env}.domain.com/foo/{v1}/{v2}/{v3}'
variables:
env:
description: Environment - staging or production
default: stage-api
enum:
- stage-api
- api
# other variables
# ...
README.md on https://github.com/swagger-api/swagger-node says 'Kick the tires. Your API is live while you edit (Did we mention no code?)' -> 'Quit faking' on the next step.
So I was under impression that Swagger will generate a fake API for me.
However, if I use such swagger.yaml:
swagger: '2.0'
info:
title: test
description: test
version: "1.0.0"
host: localhost:10010
schemes:
- https
basePath: /api
produces:
- application/json
- text/event-stream
consumes:
- application/json
paths:
/pages:
get:
summary: test
description: test
responses:
200:
description: pages
schema:
type: array
items:
$ref: '#/definitions/Page'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
(where definitions are also given in config)
I receive 404 in both curl http://localhost:10010/api/pages and swagger editor (swagger project edit). I know about x-swagger-router-controller thing but I expected it to work out of the box. Am I doing something wrong?
I should've read the docs more carefully. Swagger gives us the mock mode (swagger project start -m)