I have a micro service architecture with spring cloud gateway and each micro service has its own Open Api Spec. I need to merge all of them into 1 Open Api Spec ( yaml or json ).
I am not talking about a single swagger UI serving multiple links. I really need to merge the specs because the consumer of the spec needs a single json file.
This file is used by Open Api Validator by Atlassian.
Related
I am currently looking into adding Swagger to an API that I work on. I found rswag, but from what I can tell, I would have to manually write specs for every endpoint in my API. This API has hundreds of endpoints, so this isn't very feasible.
Django REST Framework has SchemaGenerator which can generate an OpenAPI schema, either as a static file to commit and edit as you see fit or a dynamic endpoint which can be consumed by Swagger UI. Is there any equivalent for Ruby on Rails?
As a side note, I am also using jsonapi-resources. I'd be open to tools that are specific to JSON API.
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.
I have implemented AWS API Gateway, which has many API methods. Currently, I have created a swagger definition file (JSON format) and imported this file AWS API Gateway though the "import" option available. I am also developing REST API services in springboot that gets called from the AWS API Gateway. The REST API Service has 20 API methods and I want to have these 20 API Methods in API Gateway. I do not want to manually maintain a Swagger definition file, containing the definition for these 20 API methods. I would like to know if I can generate Swagger definition file from SpringBoot API.
I know that Swagger can create HTML documentation from the REST API but I did not find any tool that could convert this HTML to a Swagger definition file. I also know that Swagger inspector can generate the definition file, but I have to manually call each service endpoints manually to create the definition file.
Is it possible to get the Swagger for an individual endpoint from Swashbuckle? I would like to be able to build individual Swagger documents from each endpoint in my API solution, rather than including all operations in all endpoints.
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.