Start a new topic

Interlinking multiple resourceAPIs

It is convenient to have multiple .rapid model files each holding a separate resourceApi api description in a large project (esp. if the project is featuring multiple microservices that provide bits of data that might be referenced between them).


Importing respective "resourceApi" bits in model prevents the generated documentation from embedding data definitions missing in the microservice.


Is there a way to generate a Documentation views that link onto each other's resources correctly?

As the currently generated documentation features links akin to


 

file:///Users/ilja/eclipse-workspace/rsrchx-api-v2/gentargets/corporate/EntitlementRequest/Documentation/generated/EntitlementRequests_doc.html#file__Users_ilja_eclipse_workspace_rsrchx_api_v2_models_corporate_EntitlementRequest_rapid____resourceAPIs_0__ownedResourceDefinitions_3

 

for all structured defined in the remote .rapid file.



Incidentally, is it possible to generate a unified "Diagram View" page? So it links all api endpoints defined in the whole project.


Ditto for other computer-readable documentation, actually: It'd be nice to have an ability to generate global, say, JSON Schema or a Swagger spec.


Ilja, great questions!  


I've created a gist here that illustrates some of the nuances of RAPID-ML imports:


https://gist.github.com/tedepstein/7302e8782c9a9ff687593af6279ff5c7



|  It is convenient to have multiple .rapid model files each holding a separate 

|  resourceApi api description in a large project (esp. if the project is featuring 

|  multiple microservices that provide bits of data that might be referenced 

|  between them).

|  

|  Importing respective "resourceApi" bits in model prevents the generated 

|  documentation from embedding data definitions missing in the microservice.

|

|  Is there a way to generate a Documentation views that link onto each other's 

|  resources correctly?


I think what you are missing is an import of the data model.  When you import the data model, your documentation should include all of the imported data types.


Importing a resourceAPI just makes its resources available as targets for reference links. The imported resources can be used explicitly as the targetResource of a referenceLink, or can be used implicitly by RAPID-ML's automatic linking and embedding rules.


The live documentation view shows that the reference properties Assignment.taxpayer and Assignment.taxFilings are automatically realized as links to the imported PersonObject and TaxFilingCollection resources, respectively.


|  Incidentally, is it possible to generate a unified "Diagram View" page? So it 

|  links all api endpoints defined in the whole project.


Currently no, but it's a great suggestion.  Right now the diagram view is always scoped to a single resourceAPI.  Hyperlinks to imported resources are shown as outward-pointing arrows, as in the taxpayer and taxFilings references here:



|  Ditto for other computer-readable documentation, actually: It'd be nice to 

|  have an ability to generate global, say, JSON Schema or a Swagger spec.


You might try experimenting with the Swagger Normalizer GenTemplate.  It has an ADDITIONAL_FILES option that you might be able to use to create a consolidated Swagger spec. 



Ted Epstein |   |       skype:ted.epstein



Ok, so I'm trying to make a "Swagger Normaliser" gen target.


I believe that I am looking at two-stage process, as all my APIs are defined in RapidML format.


First stage to convert .rapid files to swagger "Rapid X-Change Contract" format (what's the difference between "X-Change Interop" and "X-Change Contract" generators by the way?).


Second state is to assemble the bunch of swagger files generated into single file with Swagger Normaliser.


Naturally, I want to use "prerequisites" section of the top-level (Swagger Normaliser) file to achieve that.


Adding one prerequisite file works, but having two elements listed (example attached) yields following error when gradle'd.



 

$ gradle

> Task :execGenTarget
GenTargets to execute: RSRCHX_api
Adding prerequisities and determinining execution order
Final execution schedule: _root_, Search, RSRCHX_api
SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [jar:file:/Users/ilja/.gradle/caches/modules-2/files-2.1/org.slf4j/slf4j-log4j12/1.7.5/6edffc576ce104ec769d954618764f39f0f0f10d/slf4j-log4j12-1.7.5.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [jar:file:/Users/ilja/.gradle/caches/modules-2/files-2.1/org.slf4j/slf4j-simple/1.7.12/42db62298b899818ff17352cbc00050e940bbfb0/slf4j-simple-1.7.12.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an explanation.
SLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]
Thu Jul 05 15:10:40 BST 2018 - [main] Product-specified preferences called before plugin is started
Executing GenTarget _root_
Saving trace data
Executing GenTarget Search
Jul 05, 2018 3:10:40 PM com.modelsolv.reprezen.generators.api.util.GeneratorLauncher run
SEVERE: GenTarget Search failed
com.modelsolv.reprezen.generators.api.GenerationException: Multiple output items defined with name "JSON"
        at com.modelsolv.reprezen.generators.api.template.GenTemplate.define(GenTemplate.java:276)
        at com.modelsolv.reprezen.generators.api.zenmodel.ZenModelGenTemplate.defineParameterizedOutputItem(ZenModelGenTemplate.java:46)
        at com.modelsolv.reprezen.gentemplates.swagger.SwaggerContractGenTemplate.configure(SwaggerContractGenTemplate.java:27)
        at com.modelsolv.reprezen.generators.api.template.GenTemplate.initOutputs(GenTemplate.java:159)
        at com.modelsolv.reprezen.generators.api.template.GenTemplate$StaticGenerator.generate(GenTemplate.java:398)
        at com.modelsolv.reprezen.generators.api.template.GenTemplate$Generator.generate(GenTemplate.java:697)
        at com.modelsolv.reprezen.generators.api.target.GenTarget.execute(GenTarget.java:208)
        at com.modelsolv.reprezen.generators.api.target.GenTargetUtils.execute(GenTargetUtils.java:86)
        at com.modelsolv.reprezen.generators.api.target.GenTargetUtils.execute(GenTargetUtils.java:98)
        at com.modelsolv.reprezen.generators.api.util.GeneratorLauncher.run(GeneratorLauncher.java:85)
        at com.modelsolv.reprezen.generators.api.util.GeneratorLauncher.main(GeneratorLauncher.java:46)

0    [main] WARN  o.swagger.util.PropertyDeserializer  - no property from null, null, {ENUM=null, TITLE=null, DESCRIPTION=null, DEFAULT=null, PATTERN=null, DESCRIMINATOR=null, MIN_ITEMS=null, MAX_ITEMS=null, MIN_PROPERTIES=null, MAX_PROPERTIES=null, MIN_LENGTH=null, MAX_LENGTH=null, MINIMUM=null, MAXIMUM=null, EXCLUSIVE_MINIMUM=null, EXCLUSIVE_MAXIMUM=null, UNIQUE_ITEMS=null, EXAMPLE=null, TYPE=null, FORMAT=null, READ_ONLY=null, VENDOR_EXTENSIONS={}, MULTIPLE_OF=null}
1    [main] WARN  o.swagger.util.PropertyDeserializer  - no property from null, null, {ENUM=null, TITLE=null, DESCRIPTION=null, DEFAULT=null, PATTERN=null, DESCRIMINATOR=null, MIN_ITEMS=null, MAX_ITEMS=null, MIN_PROPERTIES=null, MAX_PROPERTIES=null, MIN_LENGTH=null, MAX_LENGTH=null, MINIMUM=null, MAXIMUM=null, EXCLUSIVE_MINIMUM=null, EXCLUSIVE_MAXIMUM=null, UNIQUE_ITEMS=null, EXAMPLE=null, TYPE=null, FORMAT=null, READ_ONLY=true, VENDOR_EXTENSIONS={}, MULTIPLE_OF=null}
2    [main] WARN  o.swagger.util.PropertyDeserializer  - no property from null, null, {ENUM=null, TITLE=null, DESCRIPTION=null, DEFAULT=null, PATTERN=null, DESCRIMINATOR=null, MIN_ITEMS=null, MAX_ITEMS=null, MIN_PROPERTIES=null, MAX_PROPERTIES=null, MIN_LENGTH=null, MAX_LENGTH=null, MINIMUM=null, MAXIMUM=null, EXCLUSIVE_MINIMUM=null, EXCLUSIVE_MAXIMUM=null, UNIQUE_ITEMS=null, EXAMPLE=null, TYPE=null, FORMAT=null, READ_ONLY=null, VENDOR_EXTENSIONS={}, MULTIPLE_OF=null}
Executing GenTarget RSRCHX_api
Saving trace data

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

 

Am I using the gen template format wrong? Is there an format reference for them? Recovering this knowledge from unrelated blog articles is somewhat slow.

zip
(17.4 KB)

Hi Ilja, 


It's quite possible that you've discovered a bug in Normalizer. We will take a look. However, it may not be until next week as we're currently focused on a new release...


Regards,


Ted Epstein |   |       skype:ted.epstein

No problem at all.


So I suspect that the  SwaggerNormalizerGenTemplate will actually merge data definitions to a single block, but not api endpoint lists, is this correct?

As I read the Normalizer specification, the ADDITIONAL_FILES with a RETAIN policy that includes "PATHS" or "ALL" should effectively merge all of the path items from the additional files into the generated Swagger spec. 


But it's not working in my tests. We will have to explore further next week.

Login or Signup to post a comment