Compiling Documentation
Mill includes a mill command line application for doing various tasks on your API, including compiling it down into versioned OpenAPI or API Blueprint specifications.
Mill will compile your documentation into an OpenAPI specification.
$ ./vendor/bin/mill compile docs/
Compiling controllers and representations...
Compiling OpenAPI files...
- API version: 1.0
- API version: 1.1
- API version: 1.1.1
- API version: 1.1.2
- API version: 1.1.3
Done!
If we look at the versioned directories that it created, docs/1.1, we'll see the compiled specification for v1.1 of our API.
$ ls specs/1.1
api.json tags
$ cat specs/1.1/api.json | less
{
"openapi": "3.0.2",
"info": {
"title": "Mill unit test API, Showtimes",
"description": "This is an example API for the purposes of showing how Mill works.",
"version": "1.1",
"contact": {
"name": "Get help!",
"email": "support@example.com",
"url": "https:\/\/developer.example.com\/help"
}
},
"tags": [
{
"name": "Theaters"
},
{
"name": "Movies",
"description": "These resources help you handle movies."
}
],
"servers": [
{
"url": "https:\/\/api.example.com",
"description": "Production"
},
{
"url": "https:\/\/api.example.local",
"description": "Development"
}
],
"paths": {
"\/movie\/{id}": {
"get": {
"summary": "Get a single movie.",
Mill also generates individual specifications for each of your tags.
$ ls specs/1.1/tags
Movies.json Theaters.json
These tagged specifications contain only resources and representations that are incorporated within that tag.
Mill will compile your documentation into an API Blueprint specification.
$ ./vendor/bin/mill compile --format=apiblueprint docs/
Compiling controllers and representations...
Compiling OpenAPI files...
- API version: 1.0
- API version: 1.1
- API version: 1.1.1
- API version: 1.1.2
- API version: 1.1.3
Done!
If we look at the versioned directories that it created, docs/1.1, we'll see the compiled specification for v1.1 of our API.
$ ls specs/1.1
api.apib representations resources
$ cat specs/1.1/api.apib | less
FORMAT: 1A
# Mill unit test API, Showtimes
This is the API Blueprint file for Mill unit test API, Showtimes.
It was automatically generated by [Mill](https://github.com/erunion/mill) on 2017-03-20 10:55:39.
# Group Movies
## Movies [/movies/{id}]
Information on a specific movie.
### Get a single movie. [GET]
+ Parameters
+ `id` (integer, required) - Movie ID
+ Response 200 (application/json)
+ Attributes (Movie)
Mill also generates individual parts of your documentation for you. This is helpful if you have people working on API design work, but just want to work on the API Blueprint files (and have someone else do the backend work).
$ cat specs/1.1/tags/Movies.apib | less
# Group Movies
## Movies [/movies/{id}]
Information on a specific movie.
### Get a single movie. [GET]
+ Parameters
+ `id` (integer, required) - Movie ID
+ Response 200 (application/json)
+ Attributes (Movie)
+ Response 304 (application/json)
+ Response 404 (application/json)
+ Attributes (Error)
### Update a movie. [PATCH]
This action requires a bearer token with `edit` scope.
+ Parameters
+ `id` (integer, required) - Movie ID
+ Request
+ Attributes
- `cast` (array) - Array of names of the cast.
- `content_rating` (enum[string]) - MPAA rating
+ Members
+ `G`
$ cat specs/1.1/representations/Movie.apib | less
## Movie
- `cast` (array[Person]) - Cast
- `content_rating` (enum[string]) - MPAA rating
+ Members
+ `G`
+ `PG`
+ `PG-13`
+ `R`
+ `NC-17`
+ `X`
+ `NR`
+ `UR`
- `description` (string) - Description
- `director` (Person) - Director
- `external_urls` (object) - External URLs
- `imdb` (string) - IMDB URL
