Conteneurisation Docker Swagger

Comment construire votre documentation Swagger dans une image docker

Cette documentation et les scripts template ne sont pas censés générer votre fichier swagger.json. Dans l’exemple ci-dessous vous trouverez un flux complet avec une job dotnet générant un fichier swagger.json, mais cela ne sera pas documenté dans cette section. Vous devez transférer votre fichier swagger.json à la job template en utilisant les artefacts GitLab.

Définition du job template

.build-documentation script situé dans le fichier build/.documentation-build.yml du projet IUT_INF63/generic-ci.

Job template utilisée pour construire une image docker à partir d'un fichier Swagger existant et pousser l'image construite vers le registre GitLab CodeFirst.

Liste des variables du script :

Nom de la variable	Requis	Valeur par défaut	Description
SWAGGER_JSON_PATH	OUI		Chemin du fichier Swagger depuis la racine de votre projet (par exemple docs/swagger.json)
DOC_TYPE	OUI		Indiquez quel type de documentation doit être packagé (utilisez la valeur SWAGGER).
DESTINATION_REGISTRY_IMAGE_NAME	NON	$CI_REGISTRY_IMAGE	Chemin du registre où votre image sera poussée (par exemple registry.com/mon-projet)
DESTINATION_REGISTRY_IMAGE_VERSION	NON	$CI_COMMIT_REF_SLUG	Version du registre de l'image qui sera poussée
DESTINATION_REGISTRY_PATH	NON	$CI_REGISTRY	URL du registre où l'image sera poussée (utilisée pour l'authentification, par exemple registry.com)
DESTINATION_REGISTRY_USER	NON	$CI_REGISTRY_USER	Nom d'utilisateur du registre (utilisé pour l'authentification)
DESTINATION_REGISTRY_PASSWORD	NON	$CI_REGISTRY_PASSWORD	Mot de passe de l'utilisateur du registre (utilisé pour l'authentification)

.push-documentation-image script situé dans le fichier build/.documentation-build.yml du projet IUT_INF63/generic-ci.

Job template utilisé pour pousser l'image docker vers le registre CodeFirst. Cette job DOIT être liée à une job de configuration (avec le mot-clé `needs`) !

Aucune variable pour ce script.

Exemple

stages: # Définissez au moins une étape qui correspond au stage de votre job
  - swagger
  - 🏗️build
  - 📦push

include:
  - project: 'IUT_INF63/generic-ci' # Référence au projet gitlab contenant les scripts ci génériques
    ref: 'main' # Référence à la branche du projet ci générique gitlab
    file:
      - 'build/.documentation-build.yml' # Nom du fichier à inclure

# Cette job doit être réalisée selon votre langage et votre générateur swagger.
generate-swagger-files:
  stage: swagger
  image: mcr.microsoft.com/dotnet/sdk:TODO
  script:
    - dotnet ...
    - dotnet swagger ... TO BE CONTINUED (par les étudiants bien sûr)
  artifacts: # C'est la seule partie obligatoire, vous devez marquer comme artefact votre fichier swagger.json pour pouvoir l'utiliser dans la job suivante
    paths:
      - TODO
  allow_failure: true
  rules:
    - when: manual

Ensuite dans votre .gitlab-ci.yml vous pouvez étendre ces jobs génériques pour construire votre dockerfile en image docker

build-swagger-documentation:
  extends: .build-documentation # Étendre la job générique
  stage: 🏗️build
  variables:
    SWAGGER_JSON_PATH: TODO # Emplacement du fichier swagger.json
    DOC_TYPE: SWAGGER # Type de documentation
    DESTINATION_REGISTRY_IMAGE_NAME: TODO # Ici mettez l'adresse du conteneur quand il sera stocké dans le registre
    DESTINATION_REGISTRY_IMAGE_VERSION: TODO # Ici mettez le nom que vous voulez donner à sa version
  needs:
    - job: generate-swagger-files # Configurer la dépendance entre cette job et la précédente
  rules:
    - when: manual # Vous permet de déclencher votre construction manuellement en utilisant le bouton sur l'interface GitLab

push-swagger-documentation:
  extends: .push-documentation-image # Étendre la job générique
  stage: 📦push
  needs:
    - job: build-swagger-documentation # Configurer la dépendance entre cette job et la précédente
      artifacts: true
    - job: generate-swagger-files # Récupérer le fichier swagger.json en utilisant les artefacts
      artifacts: true

Exemple de job générée

pipeline