Include multiple portman config json

[jdevosMagento]

Hello,

First of all, thank you for this tool which is really interesting!

I wanted to know if it was possible to make file inclusions in a root configuration file.

I have a big project in terms of api and I'm afraid that having everything in a single file will become unreadable.

With openapi yaml, I was able to cut out the different paths via $refs which allows you to cut out the interfaces well and find your way around easily.

Is there a similar solution with portman?

If not, what advice can you give to get organized on a project with multiple APIs?

Thank you!

[thim81]

Hi @jdevosMagento

I think you are referring to splitting up the Portman configuration (or the OpenAPI file)?

For the Portman conversion configuration, currently we expect it all grouped in 1 file.

You can include a file reference for the prerequestscripts using a "file:" syntax, to make the configuration a bit more compact.

Possible workaround

You can define the Portman configuration in JSON or YAML, what you could do is add an additional step before you run the portman conversion by leveraging a dereference package (ex: json-schema-ref-parser).

1. Dereference your your Portman config (portman-config.yaml) & save the result as a new file (portman-config.bundled.yaml)
2. Pass the bundled file to Portman portman -l your-openapi-file.yaml -c portman-config.bundled.yaml

[jdevosMagento]

Thank you for your answer, i will look at it

[thim81]

Curious how large you Portman config would be?
And if more members from the community struggle with large Portman configurations.

[jdevosMagento]

It's a big Magento e-commerce platform, with native APIs as well as specific ones to connect to several external bricks, I can't say how many exactly but there are a lot.

[thim81]

Tagging @savage-alex & @AliKhalili & @nicklloyd to capture their experience here.

[thim81]

@AliKhalili What if it is supported by default, so that it does not require any thoughts or implementation from the users?
Like OpenAPI works. You can use $ref (for easier maintenance and re-use) but you can also just keep the single file as we have right now and create a straightforward config without $ref. Portman could dereference any Portman config before the actual conversion by default.

[AliKhalili]

That is quite interesting if I can use $ref in my Portman config. it can solve growth issue of config file and at the same time we don't need to care about the maintaining different config files. Portman does that for us.

[jdevosMagento]

yes its interesting

[thim81]

Ok, given the feedback, this is a valuable feature addition for Portman.
A work item is created. Whenever we find time, we will be working on the PR for this feature.

[savage-alex]

sorry for delay in response. I have been off on sick leave. This approach sounds great!

[thim81]

@AliKhalili @jdevosMagento
The PR is in the making: https://github.com/apideck-libraries/portman/tree/277-%24ref/examples/config-references

If you have some time, have a look and see if the proposal would work?
The PR lacks some improved error handling, which will be added soon.

[AliKhalili]

@thim81 Fantastic job, well-done. It's my pleasure. I'll do that for the upcoming weekend.

[thim81]

hi @AliKhalili, @savage-alex & @jdevosMagento We just released version 1.15.0 of Portman, where this feature is included.

[thim81]

If in the coming weeks, anybody will give the '$ref' usage an attempt, if possible leave some feedback (good or bad).

[AliKhalili]

@thim81 I used this new feature, it've worked as we expected, thank you again.

[jdevosMagento]

Hello @thim81, i tested last week and it seems to work pretty well! I'm continuing the integration this week, I'll let you know.

[thim81]

@AliKhalili @jdevosMagento Are you still using the $ref option for simplifying the Portman configurations?

Since Portman config can become quite big, especially when using Variations & Fuzzing, we are wondering how we could document this capability better so that users would discover the $ref option to streamline their Portman configs?

Any tips or suggestion are welcome.

[AliKhalili]

Sorry @thim81 for delay. During the last months I have no chance to work in Portman. At that time, it worked for me very well. I am going to ask my collage to share their thoughts here.