Alexei KLENIN hosuaby

Don't and Do in OpenAPI / Swagger

If your API spec needs explanation, it's already broken.

OpenAPI has shaped the landscape of web services. With its simple and intuitive declarative syntax, a wide range of tools that can generate Swagger from code, and numerous solutions for hosting, sharing, and collaborating on interface specifications, it has become a standard in the IT industry.

But knowing how to use the tools isn’t enough. While creating a Swagger file is easy, writing one that serves as meaningful documentation requires copywriting skills, attention to detail, and the ability to anticipate all possible usage scenarios.

In this short memo, you’ll find simple, actionable advice on how to turn your OpenAPI spec into a document that provides real value — whether you’re building the service or consuming it.

Plan

Beginning
- build-tools
- Plugin abstract class
- Plugin aspects
  - ActionPlugin
  - AnalysisPlugin
  - etc...
Doing REST
RestHandler interface

Individuel

Chaussures rando
Chaussettes fines
Impermèable
Vêtements (pantalons, chemises, gants)
Sac 40-60L pour un trekking itinérant
Lunettes de soleil
Casquette
Couteau
Sac de couchage

Simple convention for naming GUI elements of Web applications

Ids or names of elements (primitives or complexes) must be written in Camel Case and must to be as short as possible. All id or name must to start with one of the defined element type prefixes.

Element type prefixes

All element ids or names must use Hungarian notation to incorporate the type of element. Prefixes are used to indicate the semantic type of the element, rather than it's underlining implementation. It means that the element of GUI with button look & feel must prefixed as btn, regardless of how it is implemented, with tag <button> or with tag <a>.
Prefixes are lowercase strings of 2, 3 or 4 characters. Here a complete list of authorised prefixes:

btn - the button or a link with a button look & feel

	import {random} from 'lodash-es';

	/**
	* This is a command to draw a random signature on the canvas of signature_pad
	* (https://github.com/szimek/signature_pad) during Cypress tests.
	*
	* Put the present into `<project root>/cypress/support/commands/signature.commands.ts`.
	* Add `import './commands/signature.commands';` in `<project root>/cypress/support/index.ts`.
	*
	* After, you will be able to draw random signatures with:

	/**
	* Primitive load-balancer to split Cypress specs across multiple runners. This script assumes that
	* all your specs are in the folder '<project root>/cypress/integration'. It uses the number of
	* tests per spec file as sole criteria to split specs between runners.
	*
	* This script accepts two arguments: the total number of runners and the index (starting from 0) of
	* the current runner. Example:
	* $ node cypress-partial.js 5 2
	* This command asks for specs to give to the third runner of five runners.
	* The output of the script is a coma-separated list of specs that can be given to Cypress. Example:

	pattern_replace removeNonWordExceptComa [[^\p{IsAlphabetic}]&&\D&&[^,]&&\S] -> ""

	pattern_replace pseudoElisionHack65Synonyms {
	pattern (\b[a-zA-Z]\')
	replacement ""
	}

	index a2_onecarrefour_instore_20200108_143341 {
	type product