keyboard

Hugo Soltys

Symfony developer

Since 2013

SoltysSlateBundle - A Symfony bundle which provides you a configurable Slate documentation for your REST APIs

Posted on by Hugo - 455 views - 0 Comments


Slate is a static documentation for your REST APIs. With it, you can create a beautiful, intelligent and responsive API documentation.

Originally developped with Ruby and Javascript, here is a bundle that allows you to make a Slate documentation in your Symfony application.


As written above, the SoltysSlateBundle provides a configurable Slate documentation for your REST APIs.

You will find here the steps you'll have to follow to use this bundle in your Symfony application.

 

Step 1: Download the Bundle

Add SoltysSlateBundle to your project via Composer:

$ composer require soltys/slate-bundle "~1"

 

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Soltys\Bundle\SoltysSlateBundle\SoltysSlateBundle(),
        );

        // ...
    }

    // ...
}

 

Step 3: Configure the Bundle

In your routing.yml file add the following lines:

# app/config/routing.yml
SoltysSlateBundle:
    resource: "@SoltysSlateBundle/Resources/config/routing.yml"
    prefix:   /api/documentation

 

Then configure the bundle by adding the following in your config.yml:

# app/config/config.yml
soltys_slate:
    language_tabs: ["shell", "ruby", "python", "javascript"]
    includes: ["SoltysSlateBundle:Slate/Includes:_errors.md.twig"]
    toc_footers: ["SoltysSlateBundle:Slate/Footers:_footer.html.twig"]

 

The full bundle configuration reference is below:

# app/config/config.yml
soltys_slate:
    title: "API Documentation"                            # Your documentation title
    navbar_path: "bundles/soltysslate/images/navbar.png"  # Your navbar image path
    logo_path: "bundles/soltysslate/images/logo.png"      # Your logo path
    with_search: true                                     # Enable/Disable the search bar
    page_classes: "index"                                 # Add this CSS class to the HTML <body> tag
    language_tabs: ["shell", "ruby", "python", "javascript"] # List the languages in which you want to write your examples
    includes: ["SoltysSlateBundle:Slate/Includes:_errors.md.twig"] # Additional templates
    toc_footers: ["SoltysSlateBundle:Slate/Footers:_footer.html.twig"] # Footer template

 

You can now install your assets with the following command:

$ bin/console assets:install web --symlink

 

Then clear your cache:

$ bin/console cache:clear

 

Step 4: Usage

To write your own documentation (unless if you like kittens), create an index.md.twig file under the app/Resources/SoltysSlateBundle/views/Slate/MarkDown directory to override the default one.

 

I hope this bundle will help you to have a beautiful API documentation :)

Leave me a comment if you have any question.

Hugo.


Hugo Soltys

My name is Hugo, I'm 25 and I'm a Symfony developer since 2013. I love to create websites by myself to learn new technologies or increase my skills.
I love movies, books, music and video games. I also like to drink a few beers with my friends. I'm from Lille (France) and I currently work as Symfony developer at Decathlon since 2016. Before that, I worked as Symfony developer for the IT Room company, in Roubaix, France.


Older articles