Writing REST API in mostly focused on planning the interface which is later accessed using curl, js, other backend systems or event mobile and desktop applications. The problem with REST API is that is not the official standard comparing to the GraphQL (relatively new offer from facebook) or Web Services (SOAP). Of course, there're many nonwritten standards like using limit and fields query params or frequently forgotten HATEOAS.

Why documenting interfaces is so important?

The main role of the interfaces is to abstract some business logic from the implementation. These interfaces are used to communicate with other objects or even humans. They don't focus on some deep implementation related issues but describes how we interact with the surrounding world which is highly important. If we know how the interface communicates with the world, we can even rewrite the whole module without worrying that something could break (of course tests also will be very welcome).

Assume we have many small interfaces to manage users, orders, invoices and so one. Each one is independent from the other and can be implemented as a separate REST API, GraphQL or Web Service (SOAP) endpoint. This is what many people call microservices. This kind of architecture doesn't need detailed documentation of the implementation. The clue is to document the interface - commands, queries, requests, responses. It is because one of the ideas behind microservices is that we can reimplement them in a few days (which could be hard if we miss documentation, specified use cases, and integration tests).

Is database schema an interface or an internal structure?

The keyword to answer this question is Big Data. By many, it's treated as a buzzword, but in this case, it is not important. The truth is that companies more often collect data from all sources, analyze them and draw conclusions which will be used to improve business workflow. Of course, many developers still think that database is an integral part of the application which is not the truth. Sooner or later one of the data analysts desires to get data also from your database. Good documentation will definitely help you to get some new friends or at least maintain the good name. Summarizing database is a kind of the interface between developers and data analysts and therefore also needs to be documented.

Documenting REST API without much effort - is it possible?

Let's start with some examples. I'll explain the basics of the swagger and show you how to generate user-friendly documentation without writing a line of "truth" PHP code.

Step 1 - Initialize composer.json and require the zircote/swagger-php library. We also add script to generate swagger.json file which will be later used to open HTML documentation.

{
    "name": "dataedo/example",
    "type": "project",
    "require": {
        "zircote/swagger-php": "^2.0"
    },
    "scripts": {
        "docs": "swagger src/"
    }
}

Step 2 - Write example API documentation. Note that we write comments in the plain PHP file. In the real world, the comments would be placed above the methods, which implement REST API endpoints. It's important to place the below file in the src directory because in the composer docs script we specified that swagger has to scan all files in the src directory (e.g., it could be named src/hello-api-documentation.php).

<?php

/**
 * @SWG\Info(title="My First API", version="1.0")
 */

/**
 * @SWG\Get(
 *     path="/api/v1/example",
 *     @SWG\Response(response="200", description="An example resource")
 * )
 */

Step 3 - Now if you run composer run docs you should see:

vagrant@homestead:~/sandbox$ composer run docs
> swagger src/

Swagger-PHP 2.0.10
------------------
    get /api/v1/example
-----------------------
1 operations documented
-----------------------
Written to /home/vagrant/sandbox/swagger.json

vagrant@homestead:~/sandbox$

Step 4 - Open the online Swagger Editor and go to File -> Import file and select generated swagger.json file. Now it doesn't look impressive, but you can see example Petstore documentation. Of course, you can host this documentation on your own server.

More advanced examples can be found in the official library documentation.

Can generating database documentation can be as simple as using Swagger?

I'm suggesting to give a chance our Dataedo product which gives you a possibility to document database structure. Generated documentation keep in sync with database changes. Your role is only to write meaningful comments for tables, columns or even user-defined modules. It is going to help keep database structure clear for huge databases with 100 or more objects.

Step 1 - Download the Lite version of Dataedo completely for free and create file repository (uncheck the "Include samples" option in the next step):

Step 2 - Click Add documentation and connect to your database. Try to go through all the steps by yourself. You don't have to worry about your database - the process of importing database performs only read operations.

Step 3 - Add some comments and start creating something truly amazing - generate documentation using only a few click. Pick the Export documentation option, choose the output format (get free trial to give a try other formats). You can check the PDF format in the Dataedo Lite Edition, so I'll show you the new HTML template (which still is in development - will be available in Dataedo 6).

More advanced details can be found in the official Dataedo documentation.