I am developing microservices using akka-http (scala). At the moment, I couldn't find any direct integration of swagger into akka-http. Nevertheless, I am starting my microservices with swagger 2.0 specs.
Now one of the challenge is to show a consolidated API spec to the consuming applications. I don't want to share multiple specs to the consumers and hence want to aggregate multiple swagger specs into one single spec (if this can be done on the fly, it would be great). Also how would this work with swagger-ui?
I suggest using as many operation references as possible:
paths:
health:
$ref: "path/to/your/operation.json"
Many people build simple routers to combine the specs into single ones, which can be quite powerful:
https://router/{service}/{all-operations-from-service}
If you have a valid spec file, then swagger-ui will be fine. There are some known issues for extremely large specs loading slowly, but consider that a bug not a limitation of swagger-ui (meaning it'll be fixed).
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.
I've recently started development on what will be come a rather large mobile application (React Native) that consumes a Ruby on Rails API (in API mode).
On the frontend I've used TypeScript extensively throughout the code but I am having issues with how to approach building types and interfaces for data received through API requests. I've heard about transpiling C# database models into TypeScript types - but I can't find anything similar for Ruby on Rails. The only thing I've been able to find is how to handle types in mono-repos where both the frontend and backend is in a single repository.
I could build my types manually on the frontend but I feel like this wouldn't be sustainable over the long term, especially when new developers join the project.
Is there any gems out there for this or would I have to write it myself? Am I approaching the issue incorrectly?
I could build my types manually on the frontend
This is probably the best choice as it encourages decoupling between the frontend and the backend API application. The whole idea of automatically generating front end code based on your database sounds good in theory but your frontend is not talking directly to the DB - its talking to your API and should have no knowledge of the underlying data storage which is an implementation detail of the API.
This is also the reason why you only see this attempted in a monorepo - it requires a tight coupling which is very undesirable. If the backend schema changes it will break clients - which would not occur if they simply communicate through a versioned API. As long as the API remains consistent the clients are isolated to a very large degree from changes on the backend and can occur in tandem.
You also have to take into consideration that ActiveRecord is extremely dynamic compared to anything written in C# and most other frameworks. Model attributes are automatically definined at runtime by reading the schema directly from the database - its all superninja level metaprogramming. So you can't use any form of static analysis to create fronend code from the backend code alone.
I am asked to choose one and the best from these two for unit and integration tests-
1. RestAssured
2. Mockmvc
The application is in Spring and Spring Boot. I have read many blogs and no clear distinction is given or I couldn't find one. For rest assured, its neat and clean code and BDD style that makes it more readable. But doesn't sound a convincing point. Some of the tests are written using Mockmvc and I am trying to write the same in RestAssured to compare the same.
I know this may sound a theoretical question but I am unable to get points in favor of one and suggest which one is better and why. Looks like a choice of flavor to me. Any views and suggestions?
You would choose MockMvc for web layer testing. These tests will allow you to validate your controller classes properly handle respective HTTP requests. Since these are practically fine grained controller unit tests, you can additionally include them as part of your apps’ code coverage percentage with tools like JaCoCo. On a side note, these tests will likely run faster than integration tests since they won’t require the web server to run on.
RestAssured is used for integration testing in your Spring Boot app. When it comes to RESTful based API integration testing and validation, RestAssured offers convenient methods to create and execute your HTTP calls with custom headers, auth, content types, query parameters, payload content, cookies, etc.
To aid your comparison check out this article - Testing Spring Boot RESTful APIs using MockMvc/Mockito, Test RestTemplate and RestAssured - it has a good explanation and robust examples on the usage for RestAssured and MockMvc.
I've been hearing a lot of developers raving about Graphql. After implementing in Ruby on Rails, I've begun to realize that it essentially does the same thing as JBuilder, which is built-in to Rails 5.
From a Rails perspective, what benefit does Graphql provide over JBuilder? Are they essentially used for the same thing? Is there something I'm missing in regards to Graphql?
One of the advantages of GraphQL is the fact, that it's a formally specified standard with its own query language.
It's safely-typed standard with its own specification. This means, you can interop with servers written in different tech stacks using the same query language and type system.
Since it's standardized, a few frontend js libs (Relay and Apollo) have taken advantage of that, making it very easy to cache and define tailored, client-scoped queries and mutations.
It exposes its own structure as so called Introspection API. This means that, you can document your API and query it using GraphQL itself - its self-descriptive. This gives a space for tooling support - example of such is GraphiQL, which allows to explore GraphQL schemas with ease. When using GraphQL, this feature is basically granted for free. You can see it in action i.e. in Github API Explorer, which also uses Ruby implementation of GraphQL AFAIK.
While most people think about it in terms of request/response, it also exposes publish/subscribe capabilities as GraphQL subscriptions via web sockets. Also within a standard.
I am building a REST Web Service layer on top of a Rails app that will be used by an Iphone application. The response format is XML.
I would like to build some acceptance tests that should be external to the rails stack (and should test everything, including the http server). The test scenarios are quite complex, involving the process of searching/posting/reviewing an order. What would be the best solution to accomplish this?
a. Ruby script using curl/curb to fetch the request and Hpricot to parse the request
b. Selenium
c. ..
It would also be nice that those tests could be used as integration tests (therefore, run on every git commit). What integration solution would you recommend?
a. Integrity
b. CruiseControl
c. something else
I've used three approaches over this last few years
Active-resource
I found this to be too concerned with looking like active-record to be a great solution. In some cases I had to patch parts of it to work as I'd like a REST client to behave.
Rest-client
This gem is very good - well documented and does works as expected. I combined this with my own simple DSL and it's worked out better than a generic testing framework
XML over HTTP
I use this for performance testing. Very flexible but the learning curve is higher than Rest-client. If you go down this approach you could use the Net::HTTP core class or the HTTParty gem (I haven't tried this but it looks great>
A really good resource is this Net::HTTP cheat-sheet
For ad-hoc testing I've also found the Rest Client add-in for Firefox very useful.
Use selenium-rc in ruby mode and you'll be a happy camper. Webrat/Cucumber already do this for you so you can just put that in a second project and run the tests that way, all you'll have to do is override the host (so instead of localhost you'll be using your domain).
As to CI I'm afraid I don't know the best one.
you can't possibly mean mks integrity...if so, the answer is anything but. CC is a good CI tool. really good.