API Blueprint + Gitlab integration Better way to document your API’s…

API blueprint is simple and accessible to everyone. Great documentation help to better understand the architecture decisions. Help to onboard new people fast and easily.

In this article, I will try to explain how to do better documentation with Aglio.

I will explain how to setup Aglio in your machine or in docker and how to use it for doing better documentation.

Setup

1. Docker setup:-

First, you will need to install the aglio image on your docker.

start your docker by using the command

docker-compose up

Then you will need to pull aglio image

docker pull christianbladescb/aglio

docker pull christianbladescb/aglio

Once you download the aglio image you can start creating files in your project.

1. Create an api_blueprint package and create your api.md file and api.apib file. I have given the example of one simple delete API.

api.md file

api.apib file

2. Compile your file with the following command.

docker run -v ~/Backend/javaprojects/scheduler-fronting-service:/tmp -t christianbladescb/aglio -i /tmp/API.md — theme-template triple -o /tmp/output.html

Above command will give you compilation error or .apib file if found any syntax error.

3. Create API.md file in root package structure and include your API blueprint file name. the example file is below —

API.md

4. Replace your service name with the appropriate project one. Once you compiled your project you can see the result on browser. you will just need to give file path.

file:///Users/vrushali/Backend/javaprojects/movie_service/output.html#delete-movie-name-delete

once you are done with using docker stop the docker by executing the following command.

docker-compose down

final api blueprint for delete API.

This way you can create simple, understandable API documentation.

Bonus: Access API documentation links publicly.

You can add this documentation on gitlab to run as your build pipeline step.

In gitlab.ci.yml file, you just need to add the following set of command and it will run as a separate step.

pages:
  stage: build
  image:
    name: humangeo/aglio
    entrypoint: [""]
  script:
  - /usr/local/bin/aglio -i API.md --theme-template triple -o public/index.html
  artifacts:
    paths:
    - public
  only:
  - master

Create an empty public/index.html file. all set..! now once your pages step is successfully complete it will give you public URL. which you can share with your colleagues and it can be accessible publicly.

Create public/index.html

If you have found this useful Click the 💚 below to show your support and share it with other fellow Medium users. stay tuned.