design/api/README.md
author ymh <ymh.work@gmail.com>
Fri, 30 Nov 2018 10:53:15 +0100
changeset 183 f8f3af9e5c83
parent 116 672e3c4bbd0c
permissions -rw-r--r--
Change the settings to avoid using Session authentication for rest framework as it raise exceptions in case client and backend are on the same domain On the filter, adapt to take into account new version of django_filters
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
116
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     1
# Generation of API documentation
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     2
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     3
The documentation use the api blueprint format ([documentation](https://apiblueprint.org)).
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     4
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     5
[Aglio](https://github.com/danielgtaylor/aglio) is used for rendering the documentation into html.
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     6
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     7
## install Aglio
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     8
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
     9
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    10
$ npm install
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    11
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    12
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    13
### Available commands
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    14
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    15
- Build the documentation (file metacategory.html)
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    16
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    17
$ npm run build
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    18
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    19
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    20
This runs the following command:
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    21
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    22
$ aglio -i metacategory.apib -o metacategory.html
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    23
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    24
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    25
- Watch the documentation.
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    26
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    27
$ npm run watch
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    28
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    29
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    30
This runs the following command:
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    31
```bash
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    32
aglio -i metacategory.apib -s
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    33
```
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    34
672e3c4bbd0c add documentation for metacategory editor
ymh <ymh.work@gmail.com>
parents:
diff changeset
    35