I'd like to create a recursive specification for my Swagger API. This concept seems to be absent from the Swagger documentation, so I suspect that it's just not possible. So I'm also open to any alternative solutions that are supported by Swagger.
For example, I'm trying to create a document-like structure. Each document has sections, and each section has both text and its own sections.
I'm planning on having API endpoints like this:
http://a.b.com/docs/{document-id}
http://a.b.com/docs/{document-id}/section/{section-id}
http://a.b.com/docs/{document-id}/section/{section-id}/section/{section-id}
http://a.b.com/docs/{document-id}/section/{section-id}/section/{section-id}/section/{section-id}
If I were using regex style, I would use something like this in the API spec:
...
paths:
/docs/{document-id}:
get:
...
/docs/{document-id}(/section/{section-id))+:
get:
...
So the questions are:
How do I represent arbitrarily nested resources in a Swagger/OpenAPI spec
Is there an alternative method that eliminates the need for recursive specification?
I'd recommend a simpler API design. In some companies, the limit is a maximum of 2 path parameters. Anything more and you're pushing the limit on usability.
Related
Currently on mine API Platform service, I've created several endpoints for same entity and I am using #Groups to filter the attributes to be returned.
I noticed that Swagger documentation is being automatically generated based on this #Groups definitions and it is creating one model for each endpoint - or each group combination.
The problem raises when I convert the Swagger definition to TypeScript interfaces, because it is generating a lot of similar interfaces.
I'd like to know if it possible to reuse the same model definition among the several endpoints, and flag which attribute is required or not to each one of them.
Thanks in advance, guys
Answer: There is no way to define which interface you want to generate / filter, that seems like a feature to add to the generator.
BTW, I think you are missunderstanding the purpouse of Groups.
You can use a Filter that applies a Group to filter attributes instead of having multiple endpoints. Ex: GET products?groups[]=READ&groups[]=GROUP_ADMIN&groups[]=CLIENT
https://api-platform.com/docs/core/filters/#group-filter
The first question I get from most of the developers I get is, Is there any way to auto generate your groovy file by by using swagger or may be plain json file?
Is there any way to do it?
I don't understand the question. What do you want to achieve? Do you NOT want to use Groovy file to define a contract? If that's the case then the answer is - you can use the Pact file (a json) to define the contract or you can plugin whatever you want. It's all written in the documentation - http://cloud.spring.io/spring-cloud-static/Dalston.SR4/multi/multi__pluggable_architecture.html.
As for Swagger we don't support it mainly because it's a schema. The reasons behind this decision are in this issue - https://github.com/spring-cloud/spring-cloud-contract/issues/136
I'm creating a template for our server-side codegen implementation, but I ran into an issue for a feature request...
The developers who are going to use the generated base want the following pattern (the generator is based on the dotnetcore):
Controllers
v{apiVersion}
{endpoint}ApiController : Controller, I{endpoint}Api
Interfaces
v{apiVersion}
I{endpoint}Api
I{endpoint}DataProvider
DataProviders
-v{apiVersion}
-{endpoint}DataProvider : I{endpoint}DataProvider
Both interfaces are the same, describing the endpoints. The DataProvider implementation will allow us to use DI to hot-swap the actual data provider/business logic layer during runtime.
The generated ApiControllers will refer to the IDataProviders, and use the actual implementation (the currently active one, that is). For that we're going to use dotnetcore's built-in dependency injection system.
However I can't seem to find a way to have the operations generator output to three different folders, based on the template. It will all end up jumbled in a single folder, and I will need to manually move them.
Is there a way to solve these requirements, or should I solve it all the time manually?
In MVC and WebApi you can add parameter constraints to your routes (see http://www.asp.net/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api-2#constraints). You can even use regular expressions for the parameter constraints. However, I'm wondering if it's possible to use regular expressions to handle API versioning where many routes could/should route to the same action.
For example, I'm trying to version my API in the actual URI like this:
/api/v3/SomeResource
Where v3 indicates that it's version 3 of the API. If I'm on version 3 of my API it is likely that many of the actions have been unchanged throughout all three versions and would hence need to respond to:
/api/v1/SomeResource
/api/v2/SomeResource
/api/v3/SomeResource
Therefore, I would like to just be able to put a regex in my route attribute like this:
[Route("api/v(1|2|3)/SomeResource")] but it appears as though it doesn't treat the v(1|2|3) as a regex and instead treats it as a literal. In other words, a request to /api/v1/SomeResource isn't going to this action.
Is it possible to accomplish what I'm trying to accomplish? is there a way to put a regex in my route?
Thanks in advance!
Take a look at this:
[HttpGet, Route("Api/v{version:int:regex(1|2|3)}/SomeResource")]
Reference:
http://sampathloku.blogspot.com/2013/12/attribute-routing-with-aspnet-mvc-5.html
No, it is not possible. Per MSDN.
A URL pattern can contain literal values and variable placeholders (referred to as URL parameters). The literals and placeholders are located in segments of the URL which are delimited by the slash (/) character.
Nor is it particularly useful in this case, because you would typically route each API version to a separate controller. Therefore, each version would require a separate route, not a single route that matches all versions.
The document which you have already linked has a section that specifically covers API versioning (although it doesn't provide much detail).
Has any one used WF Rules engine outside workflow activities WITHOUT using Rules Editor or CodeDOM?
Scenario
I am trying to use the Rule engine that ships with Workflow foundation classes with .Net Framework for a web based application. We evaluate hundreds of Validation Rules before proceeding towards a calculation engine for a complex calculation.
I have gone through many blogs which state how to use Rules engine without having to have Workflow Activities including https://github.com/geersch/WorkflowRulesEngine.
However they all eventually end up using a Rule Set Editor for defining rules. I want to declaratively define rules in an XML file
What I am looking for
I need to be able to specify Rules in simple XML without dealing with CODEDOM. CodeDOM seems to be very complex to write.
I should not be dependent on RuleSet Editor for defining rules.
Any thoughts any one ?
Don't know what kind of rules you are evaluating, but if you search a good open source rule engine, here is one.
Have a look at the following article for a strategy (not a solution) to approach the problem.
http://code.msdn.microsoft.com/windowsdesktop/Creating-Rules-Using-the-23c5d561
The serialization format for WF Rules is CodeDom.
It does not have another serialization format built-in.
If you want an alternate XML representation, you would need to create a tool to map between the representations.