What is your preferred tool to author and edit CAMARA API Specifications (OAS YAML)?

[Kevsy]

@camaraproject/codeowners

This information will help the tooling team know which tool(s) are to target to help accelerate and simplify development of CAMARA -compliant APIs. If your preferred tool is not listed, please choose 'Other' and then name the tool in a comment. Many thanks!

[GillesInnov35]

Bruno is also used.

[Kevsy]

Thanks, added!

[hdamker]

I suppose that a multiple choice would be better reflecting the actual use of tools. Independent of preferences I use both GitHub editor on web and Visual Code on local machine and would like to express that (hence I voted "other").

[jpengar]

I suppose that a multiple choice would be better reflecting the actual use of tools. Independent of preferences I use both GitHub editor on web and Visual Code on local machine and would like to express that.

+1. I chose Visual Code as the one I use most, but I also use Github web.

[bigludo7]

Same than Herbert & Jesus for me - voted.

[gunjald]

Also https://editor.swagger.io/ or desktop tool helps visualize the APIs which helps a lot to view fine details which sometimes are inadvertently missed. A final look before as web layout before a commit is useful.

[Kevsy]

Thanks @hdamker

I suppose that a multiple choice would be better reflecting the actual use of tools

I agree - but I don't believe that's supported yet. In the meantime I can include the comments here as indication of other choices/multiple choices.

Hi @gunjald

Also https://editor.swagger.io/ or desktop tool

Sure - editor.swagger.io is the second option in the poll. But please add any other desktop tool you use.

[benhepworth]

neovim in a terminal with github copilot plugin (and also VSCode sometimes)

[jpengar]

I also use the OpenAPI (Swagger) Editor VSCode extension locally in VS Code, which already provides support for Swagger UI or Redoc. I personally use Redoc a lot to preview the API specs.

[PedroDiez]

+1. Me too

[tlohmar]

which development tool allows simple integration / usage of the CAMARA linting checking?
Is there a simple way or even some guideline for integrating the CAMARA linter into VSC.

[Kevsy]

There's the Spectral VSC extension, which has a setting for 'ruleset file' . There are extensions that support YAMLLINT, e.g. this one . Or if this poll shows there is enough support for Visual Studio, we could develop a CAMARA extension that combines all the linting :)

[stroncoso-quobis]

My toolset is the following:

• VS Code + extensions
  • swagger plugin: https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer
  • redoc viewer: https://marketplace.visualstudio.com/items?itemName=Atif.vs-redoc-viewer

Regarding code management (to handle branches, commits, fork&merge)

• GitKraken

A useful tip: The "swaggerize search engine". I use search engines in order to visualize raw yaml from Github.

Chrome users:
- Configuration → chrome://settings
- Search engine → chrome://settings/searchEngines
- Introduce search engine with swagger (or redoc) editor: https://editor.swagger.io/?url=%s

Then, I can simply copy "raw" content URL from GitHub and paste it into browser navigation bar. Example: This, is simply done navigating through Github to the file of interest, then, copying the RAW URL of the yaml file to examine, and then, on my search navigation bar: "swaggerize" .

Similar trick is possible for redoc and firefox.

Hope it helps!

[shilpa-padgaonkar]

+1 to VScode & Github Editor.
Voted

[RandyLevensalor]

I use VS Code... though I find that the rule to not require a contact in the info block is ignored in VS Code. This may be a config issues on my part.

While discussing tools for APIs, it would be nice to move to editing to Jinja2 or a similar templating that we edit rather than editing the final API. With templating, we can auto apply the required text from commonalities, ICM and other copy paste text in a more consistent fashion. Then rendering the API during the commit process.

[patrice-conil]

I use IntelliJ with its bundled "Openapi Specifications" plugin.

[maxl2287]

Same here as well! :)

[caubut-charter]

Neovim with various language servers.

https://github.com/redhat-developer/yaml-language-server
https://github.com/luizcorreia/spectral-language-server
https://github.com/daveshanley/vacuum

https://github.com/neovim/nvim-lspconfig/blob/85e0dd26b710e834a105d679200d01e326a3d2b0/lua/lspconfig/configs/yamlls.lua#L4
https://github.com/neovim/nvim-lspconfig/blob/85e0dd26b710e834a105d679200d01e326a3d2b0/lua/lspconfig/configs/spectral.lua#L20
https://github.com/neovim/nvim-lspconfig/blob/85e0dd26b710e834a105d679200d01e326a3d2b0/lua/lspconfig/configs/vacuum.lua#L4

[Kevsy]

Thanks everyone for the answers!

To recap the reason for the poll: GitHub Workflows can perform post-commit checks, but not post-commit fixes (since the fix would itself be a new commit/result in a new PR). While the Workflow to run CAMARA linting post-commit is an important test, authoring tools can help ensure CAMARA-compliance at the pre-commit stage.

The goal of the poll is not to force authors to use a particular tool, but to see which tool(s) are (1) popular and (2) which we can extend to ensure CAMARA-compliance pre-commit.

Results summary

Caveat: GitHubs poll are not multiple choice, and are anonymous, but I've attempted the combine the poll results with the comments.

In the table below, 'Templating' means the ability to substitute placeholders for CAMARA values and artefacts (e.g. latest info.description templates, error structures, version and release numbers etc.).

Rank	Name	Pre-commit checks	Templating	Free
1	Visual Studio Code	✅	✅	✅
2	editor.swagger.io	✅	✅	✅
3	GitHub editor	❌	❌	✅
4	Neovim	✅	✅	✅
5	IntelliJ	✅	✅	❌
6	Bruno	❔	❔	✅
6	Jinja	❔	✅	✅

The poll shows Visual Studio Code and editor.swagger.io and as the most popular editing tools. Both of these can be extended to apply CAMARA editing style rules/templates and they are free. Visual Studio Code also has an existing Open API (Swagger) extension which could potentially by extended.

Based on the results I propose that:

1. The Tooling team investigate extensions to Visual Studio Code and editor.swagger.io
2. Authors using Neovim and IntelliJ are welcome to share best practice/extensions in a new dedicated Discussion in this repo.
3. GitHub.com in the browser remains ideal for quick fixes (typos, value updates)

Let me know your thoughts (and any errors in the table above). Thanks!