diff --git a/README.md b/README.md index b335231a57940f300118fc4ee3a9ef411502e489..1b38ade5968795f63ce999081738529affc4f738 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,99 @@ -# ARF005 -ARF005 - OpenAPIs for World Storage Representation +- [Objectives](#objectives) +- [Associated workspaces](#associated-workspaces) + - [Overview and fast access](#overview-and-fast-access) + - [ETSI Forge](#etsi-forge) + - [ETSI Lab](#etsi-lab) + - [ETSI ISG ARF Sharepoint](#etsi-isg-arf-sharepoint) +- [Selected Tools](#selected-tools) + - [Editors](#editors) + - [OpenAPI tools](#openapi-tools) + - [Development tools](#development-tools) + +# Objectives + +Project dedicated to the development of an API standardizing the exchanges with a World Storage Representation service. + +# Associated workspaces + +## Overview and fast access + +Goto | ARF|STF|Other|Description +----------|---------|--|--|-- + [ETSI Portal](https://portal.etsi.org/home.aspx ) | yes | yes |-|Portal + [Sharepoint Auth.](https://etsihq.sharepoint.com/:f:/s/Whitepapers/EoitUA6NUWtCkUe69C5x7Y4B-ctyOMXB6SX-jrR0oElYkw ) | yes | yes |-|Whitepapers| + [Sharepoint ~~Auth.~~](https://etsihq.sharepoint.com/:f:/s/Whitepapers/EoitUA6NUWtCkUe69C5x7Y4B15QjoFl-a_wpimo0hs-Jrw ) | yes | yes |-|Whitepapers| + [Teams](https://teams.microsoft.com/) |-|yes|-|STF620 + [ETSI Forge](https://forge.etsi.org/rep/arf) | yes | yes |-|Specification + [ETSI Lab](https://labs.etsi.org/rep/arf) |-| yes |-|Development + -# Workspaces ## ETSI Forge + Contains the source code and specification related to the World Storage API. -[Access to the Forge](https://forge.etsi.org/rep/arf) +- Type internal (The group and any internal projects can be viewed by any user logged in w. EOL) can be made public when needed + +**Maintainer**: Eric Villain -[Access to the project: ARF005 – World Storage API](https://forge.etsi.org/rep/arf/arf005) +- [Access to the Forge](https://forge.etsi.org/rep/arf) + +- [Access to the project: ARF005 – World Storage API](https://forge.etsi.org/rep/arf/arf005) ## ETSI Lab + Contains the source code and documentation related to the wrappers, the Unity plugin and the validation application. We will create an independent project for each item. A project called Management has already been created for administrative purpose. -[Access to the Lab](https://labs.etsi.org/rep/arf) +- Type: Internal (The group and any internal projects can be viewed by any user logged in w. EOL) can be made public when needed -[Access to the subgroup World Storage API Helpers](https://labs.etsi.org/rep/arf/world-storage-api-helpers) +**Maintainer**: Patrick Harms + +- [Access to the Lab](https://labs.etsi.org/rep/arf) + +- [Access to the subgroup World Storage API Helpers](https://labs.etsi.org/rep/arf/world-storage-api-helpers) ## ETSI ISG ARF Sharepoint + Contains temporary office documents that are edited collaboratively and all other stuff that don’t fit in the Forge or the Lab. -[Access with authentication](https://etsihq.sharepoint.com/:f:/s/Whitepapers/EoitUA6NUWtCkUe69C5x7Y4B-ctyOMXB6SX-jrR0oElYkw) +- [Access with authentication](https://etsihq.sharepoint.com/:f:/s/Whitepapers/EoitUA6NUWtCkUe69C5x7Y4B-ctyOMXB6SX-jrR0oElYkw) + +- [Access without authentication](https://etsihq.sharepoint.com/:f:/s/Whitepapers/EoitUA6NUWtCkUe69C5x7Y4B15QjoFl-a_wpimo0hs-Jrw) + +# Selected Tools + +## Editors + +- General purpose editor + - [VSCode](doc/VSCode.md) + +- Diagram editor (especially for use case diagrams) + - [Diagrams.net](http://diagrams.net) + - GUI based, easy to build diagrams, almost no learning curve, nice PNG export, easy to modify, easy to change objects positions, online and offline version, free of charge, open source. Good documentation. Used by the group in the architecture definition phase. + - Available plugin for VSCode + - [Ofline version](https://github.com/jgraph/drawio-desktop/releases/tag/v15.4.0) + +- Diagram editor (for sequence diagrams) + - [PlantUML](https://plantuml.com) + - Seems powerful (didn’t miss anything until now), small learning curve, modify with copy paste. Nicely rendered. Sometimes “compilation fails” but errors messages are explicit. + - Available plugin for VSCode -[Access without authentication](https://etsihq.sharepoint.com/:f:/s/Whitepapers/EoitUA6NUWtCkUe69C5x7Y4B15QjoFl-a_wpimo0hs-Jrw) +## OpenAPI tools -# Tools -## Swaggereditor -https://forge.etsi.org/index.php/tools/rest-apis -https://forge.etsi.org/swagger/editor/ -## API generation -https://openapi-generator.tech/ +- Swaggereditor + - [ETSI REST API tools](https://forge.etsi.org/index.php/tools/rest-apis) + - [Swagger Editor](https://forge.etsi.org/swagger/editor/) -Codegen +- API generation + - [OpenAPI generator](https://openapi-generator.tech/) -https://swagger.io/tools/swagger-codegen/ +- Codegen + - [Swagger Codegen](https://swagger.io/tools/swagger-codegen/) + - [Swagger Codegen documentation](https://swagger.io/docs/open-source-tools/swagger-codegen/) -https://swagger.io/docs/open-source-tools/swagger-codegen/ +## Development tools +- Visual Studio +- Visual Studio Code +- Unity 3D diff --git a/doc/VSCode.md b/doc/VSCode.md new file mode 100644 index 0000000000000000000000000000000000000000..b219ce49fc9846989efc64025a91bda48e9ee6da --- /dev/null +++ b/doc/VSCode.md @@ -0,0 +1,92 @@ +# VSCode / VSCodium + +## Table of content + +- [VSCode / VSCodium](#vscode--vscodium) + - [Table of content](#table-of-content) + - [VSCode vs VSCodium](#vscode-vs-vscodium) + - [Nice to have plugins](#nice-to-have-plugins) + - [Markdown Language Features (already built in)](#markdown-language-features-already-built-in) + - [Markdown All in One](#markdown-all-in-one) + - [Markdownlint](#markdownlint) + - [Draw.io Integration](#drawio-integration) + - [Markdown PDF](#markdown-pdf) + - [PlantUML](#plantuml) + - [Markdown Preview Github Styling](#markdown-preview-github-styling) + - [Markdown shortcuts](#markdown-shortcuts) + - [Markdown Snippets](#markdown-snippets) + - [Snippets ranger](#snippets-ranger) + - [Git Graph](#git-graph) + +## VSCode vs VSCodium + +VSCode is nice, but you can also use it's open source counterpart with the same functionalities and without the tracking and telemetry functionalities. + +## Nice to have plugins + +### Markdown Language Features (already built in) + +VSCode handles Markdown files by default. + +### Markdown All in One + +Extends the Markdown syntax and functionalities. + +- It brings + - GitHub Flavored Markdown + - Table of content (automated) + - Section numbers management + - Math + - Keyboard shortcuts + +### Markdownlint + +Helps keeping consistancy accross documents. + +- Can also be very annoying + +### Draw.io Integration + +- Allow to edit and render diagram. +- Provide the same functionality as the online or offline version of Diagrams.net. +Diagram.io +- Missing feature: a way to generate automatically a picture of the diagram on file save. + +### Markdown PDF + +Allow to export Markdown documents in different formats (.pdf, .html, .png, .jpg ) + +### PlantUML + +- Renders .puml files +- Configuration + - Set Plantuml:ExportFormat to png + - Set Plantuml:ExportOutDir to . + - Uncheck Plantuml;ExportSubFolder + - Set Plantuml:Java to C:\Program Files\Java\jre1.8.0_301\bin\java.exe + - Set Plantuml:Render to local + +Diagram.io + +Missing feature: no automated creation of the .png file. Need to right click on the file and choose "Export Current Diagram". + +### Markdown Preview Github Styling + +Render the Markdown file as they will look like in Github + +### Markdown shortcuts + +Create shortcuts for Markdown formatting + +### Markdown Snippets + +Add new snippets, especially to create tables. + +### Snippets ranger + +Allow to browse and edit all the default snippets. + +Note : Call snippets from intelisense with CTRL + SPACE + +### Git Graph +GitGraph diff --git a/doc/images/VSCodeDiagram.io.jpg b/doc/images/VSCodeDiagram.io.jpg new file mode 100644 index 0000000000000000000000000000000000000000..8bba8f7f6dc744d3f28d122bbf70cbe205268595 Binary files /dev/null and b/doc/images/VSCodeDiagram.io.jpg differ diff --git a/doc/images/VSCodeGitGraph.jpg b/doc/images/VSCodeGitGraph.jpg new file mode 100644 index 0000000000000000000000000000000000000000..7f3e1ac57664fab4cfab27cde839f610037784e7 Binary files /dev/null and b/doc/images/VSCodeGitGraph.jpg differ diff --git a/doc/images/VSCodePlantUML.jpg b/doc/images/VSCodePlantUML.jpg new file mode 100644 index 0000000000000000000000000000000000000000..3f3388d595d3e458a07b162c62631a4ce64c3ea4 Binary files /dev/null and b/doc/images/VSCodePlantUML.jpg differ