How to create
API blueprints

What is API Blueprint?

API Blueprint is a powerful tool for designing and documenting web APIs in a human-friendly and machine-readable format. It provides a simple yet expressive syntax to describe the endpoints, request/response payloads, and other aspects of an API.

API Blueprint files have a .apib extension and are written in plain text, making them highly portable and easily version-controlled.

The format follows a structured approach, using Markdown-like syntax to define resources, methods, headers, and parameters. Additionally, API Blueprint supports advanced features such as response examples, URI templates, data structures, and even customizable metadata.

You can access the main documentation for more information about API Blueprint by visiting the official website.

What is this project?

This project has been designed to facilitate the planning and documentation of back-end services associated with Intranet Mall projects.

By utilizing API Blueprint files, we can easily specify the endpoints and generate comprehensive documentation with a simple git push.

You can check all documented services at the home page.

How to use this project?

First, you need to have Node installed in your machine.

Additionally, if you use VSCode, it's highly recommended to install the API Elements extension to have syntax highlighting and warnings for API Blueprint files.

After that, you can follow the steps below to create an API Blueprint from scratch.

1. Clone the repository in your machine and install its dependencies

        
          git clone [email protected]:intranetmall/intranet-api-blueprint.git
          

          cd intranet-api-blueprint
          

          npm install
        
      

2. Name your service and create an .apib file inside src/api-blueprints

        
          // Example through bash terminal (optional)
          

          touch src/api-blueprints/ServiceName.apib
        
      

3. Specify your back-end service structure in your API blueprint

You can easily learn the syntax from the existing blueprints or the official examples page. Here's a hello world to get you started:

        
          # GET /message

          + Response 200 (text/plain)



            Hello World!
        
      

4. Generate documentation locally

        
          npm run generate
        
      

After running this script, all blueprints will be transformed into HTML files inside the public/blueprints folder. Then, you can open the corresponding HTML file in your browser and check the results.

5. When you're done, submit your file with git

        
          git add ./src/api-blueprints/ServiceName.apib
          

          git commit -m "feat: create service-name api blueprint"
          

          git push
        
      

6. Wait a few minutes

With the correct permissions, Vercel will take care of the rest and your documentation file should be deployed and accessible from the home page in a few minutes 🎉.