How to add a Gitlab CI job to validate generated open-api documentation is up-to-date

Question

(In my project I have docs folder and under the folder I have open-api.yaml)

The OpenApi documentation files are generated running./mvnw verify

I would like to add a Gitlab job where I do the next steps:

I have to create a pre-script to run./mvn verify

Then, Check if the generated files are different that the ones in git

If files are different, it means the openapi was not properly updated and need to give an error.

Could you please help me?

Answer 1

You can use git diff --exit-code after running the generation script to assert whether files have changed.

For example, suppose you modify an existing file then run git diff --exit-code , the command will exit non-zero. In a gitlab job, that means the job will fail.

$ echo "foo" >> existing-file.txt
$ git diff --exit-code # exits non-zero (failure)

So, you could have a gitlab job that runs your generation script then checks if the files have changed. If the files don't change, the command exits 0 and the job passes.

check_openapi:
  stage: .pre
  # ...
  script:
    - ./mvnw verify  # generate the openapi docs
    - git diff --exit-code  # fails if the files tracked by git have changed

It's important to note that git diff will only work on tracked git files. Therefore, if your generation code potentially adds new files, you should make sure that you run git add --intent-to-add for any newly created files. Otherwise, you may miss some cases because new files aren't tracked by git by default. You can add this to the CI job or you can incorporate it into your code generation script.

In example:

$ echo "foo" > newfile.txt
$ git diff --exit-code  # exits 0 (success?!)

$ echo "foo" > newfile.txt
$ git add --intent-to-add ./newfile.txt
$ git diff --exit-code # exits non-zero (failure)

So, if your generation script doesn't run git add --intent-to-add as part of its process, a complete solution may look like this:

check_openapi:
  stage: .pre
  # ...
  script:
    - ./mvnw verify
    - git add --intent-to-add .  # make sure new files are tracked/diff'd
    - git diff --exit-code