we have schemas in our swaggers: like this:
if we have many microservices and use them in many other API routes in another service.
when s.th change we need to change all schemas in all of our repositories
EXAMPLE:
I have this microservice:
survey.com/api/docs
and I want to use json sample shema in many other microservice like this:
app1.com/api/docs
and
app2.com/api/docs
and
app3.com/api/docs
when we add a property to my main microservice and schema changed I should refactor all my other schemas in other git repositories.
is there any way to map one route to another swagger document to read these schemas from there?
is there any way to manage these changes? by versioning?
if app1 and app2 and app3 use one route with schema and source API route schema of survey.com changed we should modify all our swagger documentation
Related
The company I work for has a set of microservices that each focuses on a different business capability e.g. payments, transactions, accounts, etc.
We create Open API specs in Swagger Hub (API first design) for each business capability.
Our services are predominantly .NET Core applications running in Kubernetes and we use the Swashbuckle.AspNetCore library to auto generate the Swagger UI from the yml spec (which we copy across manually from Swagger Hub). We've also discussed using .NET attributes to auto-generate the OASs from code, which I'll bring up again below.
Our public clients (native apps & web SPAs) consume multiple business capability APIs and it doesn't really seem optimal to give the public client developers (who are mostly outsourced) multiple OASs i.e. one per business capability. There's also multiple partnerships in the works and I don't think it would look professional to give them 15 different API specs... Ideally we'd have a single API spec for each specific type of consumer (e.g. "Product X public client API", and/or "Product X back-end integration API") that can be broken down into separate categories for each business capability e.g:
Also, some of the operations on a specific business capability might be for different consumers (e.g. public clients or back-end integrations). We could probably work this out by the security scheme (i.e. whether user tokens or M2M tokens are required):
If we continue with the current approach of defining API specs in Swagger Hub for each business capability, we'll need to create an additional aggregated (and partially duplicated) API specs targeted at specific consumers that we would need to continually update manually.
We could switch to defining the aggregated (consumer focused) APIs specs in Swagger Hub, but then we'll need a different way to generate Swagger UI in the microservice applications. Perhaps we could use the attribute based approach mentioned previously to generate the Swagger UI for microservices, but then there's no guarantee it will perfectly align with the aggregated OAS defined in Swagger Hub... before we rush head first down this path, the question is;
Is it possible and are there any tools to merge separate OASs in an automated or semi-automated way (ideally with some basic filtering capabilities i.e. to filter operations based on security tags) so that we don't need to maintain separate aggregated OASs manually? Alternatively, are there any other approaches to solving this problem in a more automated way?
Is it possible and are there any tools to merge separate OASs in an automated or semi-automated way
You can use APIMatic's API spec merge feature to automatically merge your specs and then transform the merged output into OpenAPI's format. Here are the steps:
Structure your directory as follows:
dir\
accounts\
openapi.json
payments\
openapi.json
transactions\
openapi.json
APIMATIC-META.json
A minimalistic metadata configuration file APIMATIC-META.json can look like this to enable merging:
{
"MergeConfiguration": {
"MergedApiName": "Product X",
"MergeApis": true,
"MergeSettings": {
"SkipCodeGenValidation": true
}
}
}
ZIP the directory, upload it and transform it via their website to OpenAPI v3 to get your merged output. Here is a link that provides step by step guide on uploading and performing a transformation manually through the website: https://docs.apimatic.io/manage-apis/api-merging/#transforming-the-zipped-file. Since you are looking for automation, APIMatic has an API to achieve the same too: https://www.apimatic.io/docs/api#/http/api-endpoints/transformation/transform-via-file
ideally with some basic filtering capabilities i.e. to filter operations based on security tags
An OAS API spec you provide in the directory can have a metadata configuration file provided next to it as well which can contain filtering options to take out certain operations. Please see detailed reference document on this here: https://docs.apimatic.io/manage-apis/apimatic-metadata/#filtering-out-parts-of-api-definition-with-metadata
So, your directory structure can then look like the following:
dir\
accounts\
openapi.json
APIMATIC-META.json
payments\
openapi.json
APIMATIC-META.json
transactions\
openapi.json
APIMATIC-META.json
APIMATIC-META.json
The inner metadata files can have a configuration like the following:
{
"KeepEndpointsWithTags": ["public"]
}
When you ZIP the directory, upload and transform it, the output OAS would be the merged output of your "filtered" input OAS files. Note, however, that this filtering isn't based on security level information. It is based on the tags configured at operation level.
Is there a way to group all CRUD operations as ANY method in swagger 2?
I've looked at their docs here and here and it doesn't look like there is. They allow grouping with tags only. I'm using swagger in the body of my CloudFormation template "Type": "AWS::ApiGateway::RestApi" to provision a resource URL that takes all CRUD operations which in AWS that will be ANY.
I defined APIs through swagger. For each micro-service, I have a swagger file say micro-service1.yaml.Like that I have around 40 micro-services. Accessing each one is difficult . I want to access all of the through a common URL.How can I achieve the same. Thanks in advance!
One option is to use WebSphere Liberty, since it will aggregate all the APIs running in it and show you them in a single Swagger UI.
However, for 40 micro-services the recommended topology would be to separate them into different WebSphere Collective members (Java w/ Liberty or Node w/ Loopback), where either of them can be inside a Docker container), so you could see all the APIs from the aggregated Collective Controller Swagger UI.
More info in this blog.
I've included swagger bundle in each of my dropwizard service. I was wondering if we can run swagger independently and connect to each service so that user can have a centralised view of all services through one UI.
I'm not aware of something that lets you do that at the moment with Swagger UI specifically, but you might check out DynamicApis.com. They let you host multiple swagger documents and provide some really nice additional value for your APIs as well. They take your Swagger JSON and build you your own API portal out of them. They also have native REST API integration where you can automatically sync up your API to your portal or you can manually upload them.
Here is an example portal they have up to demonstrate how multiple APIs can be hosted and how you see them.
Here is an example of what their documentation for each API looks like. Kind of like Swagger UI++.
You can have multiple swagger instances in a single DW service. The UI, however, does not allow you to point to each of them independently. It's easy enough though to modify index.html to allow the user to select the swagger definitions that you have in the deployment.
Imagine two Grails applications which share a domain class. Maybe a Book domain class.
One application is identified as the owner of the data, one will have to access the domain data. Something like amazon and the amazon web services.
I guess it is trivial that the owning application will use a normal domain class and will expose the data through web services - no problem in grails.
But what would be best practice to implement the domain in the other application?
use a service to access the remote domain and not implement a local domain class at all?
implement a local domain class, overwrite the get()-method in order to fetch the remote data and use the local database as cache?
what other solution comes to your mind?
Ryan Geyer has a very interesting article Modularizing your Grails application domain classes which lists 3 solutions to this problem:
As a RESTful JSON Service - easy to get this setup in Grails but then you lose the automatic GORM functionality.
Separate out the domain classes into a library JAR file and reference that library in both of my other applications. This is not as easy as it first sounds
Create a Grails plugin. Put the domain object in the plugin. Each of your applications can then import this plugin. You can then create different controllers with different functionality as required. The sample code for this is available at:
git clone git://ec2.nslms.com/grails/blog_example_modular
Ted Naleid gives a great tip later in the post and recommends...
"create a grails-app/conf/BuildConfig.groovy file and put the plugin name and path to the source in it. ... If you do this, your applications will see the live changes to your domain/controller/service/etc classes as if they were actually in current app and there isn't any need to repackage and reinstall the plugin when you make changes."
Using memcache should enable both applications to have a consistent view of the data and would avoid each individual application having it's own inconsistent cache.
I think you can make JAR file of your domain classes and add reference to other grails application .
Found another interesting solution:
Riak is a key/value database with a first class REST API. There is a grails plugin for riak which maps most of the GORM functionality (relations, dynamic finders etc) to the REST API of riak: http://grails.org/plugin/riak
Now comes the part which I haven't tested yet: if you make use of the DataSources feature of grails 2.0, it should be possible to only connect those "remote" domains to a riak database.
As a result, there would be a domain stored in a riak database and several applications would be able to access it via a clean REST API without effort.
OK. This also show how silly my question is - it would be the same if you connect several apps through the same SQL-database. But sometimes people want to have something more funky like webservices.