We don't know the development tools CAMARA API authors use

[Kevsy]

Problem description

By knowing the development tools used, we can consider whether to provide other tools (beyond GitHub worklows and actions) to accelerate and simplify the development of CAMARA APIs.

Possible evolution

Mail the CAMARA codeowners with a poll asking which development tools they use to develop and edit CAMARA APIs

Alternative solution

Additional context

[tlohmar]

@Kevsy , thanks for putting out the questionnaire on the OpenAPI Spec editor.

Do you plan to give some recommendations on text and image editors / solutions, which are essential for readable API documentation?

[Kevsy]

Thanks @tlohmar - yes, good idea regarding the image editors.

Ideally:

• it should be possible to edit and make a pull request for an image which suggests e.g. Mermaid rather than static images which require modification by the original image creator.

• CAMARA should have an 'image style' that was consistent across API documents. That means agreeing a catalogue of icons to select from.

I'm not sure what you mean by 'text editors' for readable API documentation...? I agree that readable documentation is important, but that seems to be more of a question for API Design guidelines.

[hdamker]

I'm not sure what you mean by 'text editors' for readable API documentation...? I agree that readable documentation is important, but that seems to be more of a question for API Design guidelines.

I suppose we shouldn't care about the text editor to use. But we have the clear guideline of using Markdown for documentation text. And also for Markdown it would be possible to use linting (rules) to ensure proper formatting.

[tlohmar]

Maybe image handling is more important than text. Yes, 'mermaid' is a good tool for state diagrams and sequence diagrams. But it might be not the best tool for drawing block diagrams or other illustrations. I guess, the best is to store an editable PowerPoint, SVG or draw.io document somewhere in the repo and link a PNG or JPG from the markdown.

I am using VS code for the text editing together with a Markdown previewer. There might be better solutions, incl spell checking.

[Kevsy]

Good point - I checked Mermaid and they have added many new diagram types including architecture , block, user journey, flowchart.

E.g. basic architecture diagram copied-and-pasted from the Mermaid site:

architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service disk1(disk)[Storage] in api
    service disk2(disk)[Storage] in api
    service server(server)[Server] in api

    db:L -- R:server
    disk1:T -- B:server
    disk2:T -- B:db

Loading

[tlohmar]

Hello again.

I have tried to use mermaid within the info.description section of a yaml file. I realized, that the info.description section uses a dialect of Markdown, called CommonMark. So far, I have not managed to get mermaid scripts rendered.

Does anybody have a hint of getting mermaid scripts rendered within a info.description section?

[Kevsy]

HI @tlohmar - yes good point...

GitHub Markdown is based on CommonMark, which supports fenced code blocks. The CommonMark info mark indicates the language of a code block, which allows GitHub to detect a Mermaid diagram and render it.

Swagger UI does not support the Mermaid info mark natively - so Mermaid diagrams won't appear in info.description - however, there is a plugin and an action which we may be able to use to render the Mermaid diagrams as image files. This should still ensure that the editors can simply edit the Mermaid syntax to update diagrams.

Overall I think the goal should be:
1- ability to easily edit images
2- consistent design style across CAMARA

...so hopefully Mermaid can provide that, but yes we need to make sure it can render in the YAML files.

[Kevsy]

Update: the plugin/action above is designed for .md and not YAML, so will need some rework. Meanwhile the guidance suggested by @tlohmar for image best practice is discussed here