OpenAPI development guidelines - Revision history

Velez at 16:57, 26 March 2024

2024-03-26T16:57:26Z

← Older revision		Revision as of 17:57, 26 March 2024
Line 1:		Line 1:
	OpenAPI Specification (OAS) development guidelines for ETSI MEC ISG API specifications.		OpenAPI Specification (OAS) development guidelines for ETSI MEC ISG API specifications.

	''(More general recommendations can be found at [~~https:~~//forge.etsi.org/wiki/index.php/Main_Page Forge OpenAPI Guidelines])''		''(More general recommendations can be found at [//forge.etsi.org/wiki/index.php/Main_Page Forge OpenAPI Guidelines])''

	= Latest versions =		= Latest versions =

	Latest versions of the OAS representations are available in their respective repositories ([~~https:~~//forge.etsi.org/rep/mec here])		Latest versions of the OAS representations are available in their respective repositories ([//forge.etsi.org/rep/mec here])

	Latest CI test results of the OAS representations are available [~~https:~~//forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ here]		Latest CI test results of the OAS representations are available [//forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ here]

	= Contributing =		= Contributing =
Line 13:		Line 13:
	If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI].		If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI].

	ETSI CTI has also made a [~~https:~~//www.youtube.com/watch?v=YXO0R61Dcg8 YouTube] tutorial available (based on NFV) that provides guidance on how to contribute for MEC.		ETSI CTI has also made a [//www.youtube.com/watch?v=YXO0R61Dcg8 YouTube] tutorial available (based on NFV) that provides guidance on how to contribute for MEC.

	= API development =		= API development =
Line 19:		Line 19:
	== General guidelines ==		== General guidelines ==

	As of January 2021, OAS representations have been updated to reflect the latest released versions of their corresponding GS (e.g. v2.1.x); the representations follow [~~https:~~//swagger.io/specification/ OpenAPI 3.0 specification] language.		As of January 2021, OAS representations have been updated to reflect the latest released versions of their corresponding GS (e.g. v2.1.x); the representations follow [//swagger.io/specification/ OpenAPI 3.0 specification] language.

	The following figure provides a high level overview of the OAS creation and usage.		The following figure provides a high level overview of the OAS creation and usage.
Line 137:		Line 137:
	- Code generation succeeds		- Code generation succeeds

	- Sometimes, when generating code, it may be necessary to include the file [~~https:~~//github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/empty.proto empty.proto]		- Sometimes, when generating code, it may be necessary to include the file [//github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/empty.proto empty.proto]

	Example generate Go and Java		Example generate Go and Java
Line 150:		Line 150:

	== Branching strategy ==		== Branching strategy ==
	Development follows a simplified version of the popular [~~https:~~//nvie.com/posts/a-successful-git-branching-model/ GitFlow]		Development follows a simplified version of the popular [//nvie.com/posts/a-successful-git-branching-model/ GitFlow]
	* <code>master</code> - released version of the OAS representation		* <code>master</code> - released version of the OAS representation
	* <code>develop</code> - final versions of OAS representations development, before they are approved to be merged on master		* <code>develop</code> - final versions of OAS representations development, before they are approved to be merged on master

Velez at 09:47, 1 December 2021

2021-12-01T09:47:00Z

← Older revision		Revision as of 10:47, 1 December 2021
Line 22:		Line 22:

	The following figure provides a high level overview of the OAS creation and usage.		The following figure provides a high level overview of the OAS creation and usage.
	[[File:ToolchainOverview.png\|center\|thumb\|500x500px]]		[[File:ToolchainOverview.png\|center\|thumb\|500x500px\| class=img-responsive]]

	As shown on the figure, OAS YAML file is used in 3 different contexts:		As shown on the figure, OAS YAML file is used in 3 different contexts:

Carignani at 07:53, 23 February 2021

2021-02-23T07:53:27Z

← Older revision		Revision as of 08:53, 23 February 2021
Line 22:		Line 22:

	The following figure provides a high level overview of the OAS creation and usage.		The following figure provides a high level overview of the OAS creation and usage.
			[[File:ToolchainOverview.png\|center\|thumb\|500x500px]]
	[[File:ToolchainOverview.png]]

	As shown on the figure, OAS YAML file is used in 3 different contexts:		As shown on the figure, OAS YAML file is used in 3 different contexts:
Line 38:		Line 37:

	The following figure outlines doc2oas usage.		The following figure outlines doc2oas usage.
			[[File:Doc2oasToolchain.png\|center\|thumb]]
	[[File:Doc2oasToolchain.png]]

	Step 1 - Create <code>MEC-XYZ_config.yaml</code> file		Step 1 - Create <code>MEC-XYZ_config.yaml</code> file

Carignani: /* API development */

2021-02-23T07:51:30Z

API development

← Older revision		Revision as of 08:51, 23 February 2021
Line 23:		Line 23:
	The following figure provides a high level overview of the OAS creation and usage.		The following figure provides a high level overview of the OAS creation and usage.

	[File:ToolchainOverview.png]		[[File:ToolchainOverview.png]]

	As shown on the figure, OAS YAML file is used in 3 different contexts:		As shown on the figure, OAS YAML file is used in 3 different contexts:
Line 39:		Line 39:
	The following figure outlines doc2oas usage.		The following figure outlines doc2oas usage.

	[File:Doc2oasToolchain.png]		[[File:Doc2oasToolchain.png]]

	Step 1 - Create <code>MEC-XYZ_config.yaml</code> file		Step 1 - Create <code>MEC-XYZ_config.yaml</code> file

Carignani: /* OAS YAML Validation */

2021-02-23T07:51:11Z

OAS YAML Validation

← Older revision		Revision as of 08:51, 23 February 2021
Line 23:		Line 23:
	The following figure provides a high level overview of the OAS creation and usage.		The following figure provides a high level overview of the OAS creation and usage.

	~~<INSERT -~~ ToolchainOverview.png>		[File:ToolchainOverview.png]

	As shown on the figure, OAS YAML file is used in 3 different contexts:		As shown on the figure, OAS YAML file is used in 3 different contexts:
Line 39:		Line 39:
	The following figure outlines doc2oas usage.		The following figure outlines doc2oas usage.

	~~<INSERT - doc2oasToolchain~~.png>		[File:Doc2oasToolchain.png]

	Step 1 - Create <code>MEC-XYZ_config.yaml</code> file		Step 1 - Create <code>MEC-XYZ_config.yaml</code> file

Roymic at 13:18, 22 February 2021

2021-02-22T13:18:41Z

← Older revision		Revision as of 14:18, 22 February 2021
Line 175:		Line 175:
	│ └── services Protobuf services		│ └── services Protobuf services
	├── README.md General API information		├── README.md General API information
	├── MEC-XYZ.json Auto-generated JSON (From Swagger Editor -> Save As json)		├── MEC-XYZ.json Auto-generated JSON (From Swagger Editor -> Save As json)
	└── MEC-XYZ.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.		└── MEC-XYZ.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.
	</pre>''NOTE: Naming of of the JSON and YAML files is generally chosen by the DECODE group and does not necessarily follow the pattern outlined above.''		</pre>''NOTE: Naming of of the JSON and YAML files is generally chosen by the DECODE group and does not necessarily follow the pattern outlined above.''

Roymic: Fixed directory structure

2021-02-22T13:18:10Z

Fixed directory structure

← Older revision		Revision as of 14:18, 22 February 2021
Line 175:		Line 175:
	│ └── services Protobuf services		│ └── services Protobuf services
	├── README.md General API information		├── README.md General API information
	├── ~~RniAPI~~.json Auto-generated JSON (From Swagger Editor -> Save As json)		├── MEC-XYZ.json Auto-generated JSON (From Swagger Editor -> Save As json)
	└── ~~RniAPI~~.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.		└── MEC-XYZ.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.
	</pre>		</pre>''NOTE: Naming of of the JSON and YAML files is generally chosen by the DECODE group and does not necessarily follow the pattern outlined above.''

Roymic at 22:46, 19 February 2021

2021-02-19T22:46:08Z

← Older revision		Revision as of 23:46, 19 February 2021
Line 66:		Line 66:
	\|<nowiki>- No remaining warning or errors when opening OAS YAML</nowiki>		\|<nowiki>- No remaining warning or errors when opening OAS YAML</nowiki>
	\|-		\|-
	\|Swagger-UI		\|Swagger-CLI
	\|~~<nowiki>~~- ~~No error when viewing~~ the ~~file via~~ Swagger ~~UI<~~/~~nowiki>~~		\| - Part of CI validation done via Jenkins in the repository
			- Swagger-CLI reports no error/warnings

	- ~~Thorough visual inspection of endpoints and data model~~		- <code>swagger-cli validate <oas-file.yaml></code>
	\|-		\|-
	\|Speccy		\|Speccy

Roymic: Fixed sentence

2021-02-19T22:43:14Z

Fixed sentence

← Older revision		Revision as of 23:43, 19 February 2021
Line 41:		Line 41:
	<INSERT - doc2oasToolchain.png>		<INSERT - doc2oasToolchain.png>

	Step 1 - Create <code>MEC-XYZ_config.yaml</code> file -- this file contains all external types not defined in the GS in (OAS language)		Step 1 - Create <code>MEC-XYZ_config.yaml</code> file
	* existing config files can be used as a template, ~~many~~ types can be re-used		* this file contains all external types not defined in the GS in (OAS language)
	* to quickly identify external types, Step2 can be performed with an empty config file - the resulting yaml file will show all unresolved types in the ~~OAS editor~~
			* existing config files can be used as a template, types can be re-used from existing config files
			* to quickly identify external types, Step2 can be performed with an empty config file - the resulting yaml file will show all unresolved types in the Swagger Editor

	Step 2 - Use the <code>doc2oas.sh</code> script to generate <code>MEC-XYZ.yaml</code>		Step 2 - Use the <code>doc2oas.sh</code> script to generate <code>MEC-XYZ.yaml</code>

Roymic: Removed unused section

2021-02-19T22:30:29Z

Removed unused section

← Older revision		Revision as of 23:30, 19 February 2021
Line 175:		Line 175:
	└── RniAPI.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.		└── RniAPI.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.
	</pre>		</pre>

	~~=== File names ===~~

	~~The naming schema provided in the examples for the "Repository structure" above is followed.~~