Skip to content

Commit 2a93e99

Browse files
author
Gornicki, Lukasz
committed
extending the workshop script
1 parent 16c4631 commit 2a93e99

5 files changed

Lines changed: 270 additions & 83 deletions

File tree

‎README.md‎

Lines changed: 59 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,59 @@
1-
This is a script for a workshop about documenting REST APIs.
2-
This is a technical script that will be just a part of the workshop. It covers the setup of documentation portal but not the part where we learn about REST API
3-
4-
## Prerequisites
5-
6-
You need to have the following software/modules/applications installed on your computer to be able to complete all the steps of the workshop.
7-
8-
- Install Node.js and NPM: https://nodejs.org/en/download/ (both in one package) and then install:
9-
- [DocPad](http://docpad.org/) by calling in the terminal: `npm install -g npm`
10-
- [Gulp](http://gulpjs.com/) by calling in the terminal: `npm install -g gulp-cli`
11-
- Get GitHub account: https://github.com/
12-
- Install GitHub Desktop: https://desktop.github.com/
13-
- Install some nice text editor like [Atom](https://atom.io/) or [Sublime Text](https://www.sublimetext.com/)
14-
15-
## Configuring documentation publishing pipeline
16-
17-
First you need to fork some projects and configure them correctly to set up the documentation independent generation pipeline.
18-
19-
1. Fork the following repos (it means open the links and click on Fork button in the top right corner of the page):
20-
- API Doc portal template: https://github.com/hybris/docpad-skeleton-apidocs
21-
- Sample REST API microservice that we will be documenting: https://github.com/derberg/minerva
22-
- Sample registry that integrates the template and docu sources: https://github.com/derberg/apidoc-workshop-docu_registry
23-
24-
2. Configuration
25-
- Modify `chewieConfig.js` file in forked `docpad-skeleton-apidocs` repository. Change the `path` attribute:
26-
```
27-
path: process.env.REGISTRY_PATH || 'https://github.com/derberg/apidoc-workshop-docu_registry.git'
28-
```
29-
The git url must point to your forked `apidoc-workshop-docu_registry` repository.
30-
31-
- Modify `minerva.json` file in forked `apidoc-workshop-docu_registry` repository. Change the `location` attribute:
32-
```
33-
"location": "https://github.com/derberg/minerva"
34-
```
35-
The git url must point to your forked `minerva` repository.
36-
37-
## Start the API Doc portal locally
38-
39-
If configuration is completed you have to:
40-
41-
1. Clone your forked `docpad-skeleton-apidocs` repository,
42-
43-
2. Navigate to its local clone in the terminal,
44-
45-
3. Call the following command: `npm start`
46-
47-
4. Once the start is completed, open in the browser the following link: http://localhost:9778/
48-
49-
## Publishing to GitHub Pages
50-
51-
The easiest solution is to publish the API Doc portal on GitHub pages. Of course the generated API Doc portal files can be hosted on any other server as it is pure static content.
52-
53-
1. Create new repository with the following name: `your_github_username.github.io`. It must be public and initialized (You do it in UI during creation).
54-
55-
2. Modify `chewieConfig.js` file in forked `docpad-skeleton-apidocs` repository.
56-
- Change the `srcLocation` attribute:
57-
```
58-
srcLocation: 'https://github.com/derberg/derberg.github.io.git',
59-
```
60-
The git url must point to your newly created `your_github_username.github.io` repository.
61-
- Change the `docuUrl` attribute:
62-
```
63-
docuUrl: process.env.docuURL || 'http://derberg.github.io',
64-
```
65-
The page url must be the same as the name of your newly created `your_github_username.github.io` repository.
66-
67-
3. Modify `docpad.coffee` file in forked `docpad-skeleton-apidocs` repository. Change the `url` attribute:
68-
```
69-
environments:
70-
prod:
71-
templateData:
72-
site:
73-
url: "http://derberg.github.io"
74-
```
75-
It should point to the following url: `http://your_github_username.github.io`
76-
77-
4. Navigate to the local clone of `docpad-skeleton-apidocs` repository in the terminal
78-
79-
5. Call the following command: `npm run production`
80-
81-
6. Call the following command: `gulp pushResult`
82-
83-
7. Once the push is completed, open in the browser the following link: http://your_github_username.github.io
1+
## REST API -> The easiest and coolest docu to write
2+
3+
This is a script for a workshop about documenting REST APIs. The workshop covers two aspects:
4+
- Learning what REST API is,
5+
- Setting up a portal with REST API documentation.
6+
7+
## Intro
8+
9+
REST API in most cases is used in the cloud environment. It you are documenting REST API for cloud - you are lucky because:
10+
- You most likely have not only production but also stage environment set up permanently. This means you have a playground where you can check the API before you document it:
11+
```
12+
Like for the sake of this workshop we have a real service running.
13+
Just navigate to this link in the browser:
14+
http://minerva.cfapps.io/events
15+
```
16+
- In cloud all the peaces are independent and super easy to set up locally.
17+
```
18+
Minerva service mentioned above is also easy to set up locally. Just follow below steps in the terminal:
19+
> git clone https://github.com/derberg/minerva.git
20+
> cd minerva
21+
> npm install
22+
> npm run develop
23+
```
24+
- REST is easy to learn.
25+
```
26+
Again navigate in the browser to the Minerva service:
27+
http://minerva.cfapps.io/events
28+
What just happened? You `GET` an info from the server!
29+
Same thing happens once you open in a browser any Web page.
30+
) Use for example a Chrome browser and go into the `Inspector` mode
31+
) Open https://www.google.com
32+
) See the first call in the `Network` tab. You `GET` pure HTML only
33+
```
34+
- Whole Web speaks `REST`. Once you understand its rules, you'll understand how everything works on the Web.
35+
```
36+
Why you can have an unofficial Twitter app on your mobile?
37+
Why you can have 3rd party apps in Facebook
38+
Why you can have a Google Map on your Web page
39+
```
40+
41+
## Details
42+
43+
### Consuming and Theory
44+
45+
- [API Clients](docu/apiclients.md)
46+
- [API Reference](docu/apireference.md)
47+
48+
### Technical
49+
50+
Let us document our own service and publish documentation for it to a public server.
51+
52+
- [Prerequisites](docu/prerequisites.md)
53+
- [Set up and publishing](docu/using_docu_tool.md)
54+
55+
### Extra tasks
56+
57+
- Write a `Details` document,
58+
- API specification requires update in the schema for errors part
59+
- Now create a automated pipeline that will pick your changes and deploy to GitHub Pages. Use https://travis-ci.org/

‎docu/apiclients.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## API Clients
2+
3+
Generic clients:
4+
- Command line: https://curl.haxx.se/docs/manpage.html and `curl http://etc-conference.eu/`
5+
- UI: Postman or any other Chrome or Firefox plugin
6+
- Code based: https://github.com/danwrong/restler
7+
8+
API Specific clients
9+
- https://github.com/lesstif/jira-rest-client
10+
- https://github.com/DracoBlue/node-facebook-client
11+
- http://derberg.github.io/services/minerva/latest/client.zip

‎docu/apireference.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# API Reference
2+
3+
Let us talk about the REST API specification (yawn)
4+
5+
HTTP/1.1 Specification: https://tools.ietf.org/html/rfc2616
6+
7+
## Theory
8+
9+
### Base URI and Paths/Endpoints/Resources
10+
11+
Base URI: `http://minerva.cfapps.io`
12+
13+
and
14+
15+
Paths/Endpoints/Resources: `/events` or `/events/{eventId}`
16+
17+
### Methods
18+
19+
Most commonly used:
20+
- GET
21+
- POST
22+
- PUT
23+
- DELETE
24+
25+
Make a GET call to http://minerva.cfapps.io/events
26+
27+
### Query params
28+
29+
So called optional parameters.
30+
Its about limiting and specifying response.
31+
32+
Make a GET call to http://minerva.cfapps.io/events?q=type:"Conference 2016"
33+
34+
### Headers
35+
36+
Response and request.
37+
38+
Make again a GET call to http://minerva.cfapps.io/events
39+
Notice all the different headers, content type or length.
40+
41+
### Body/Payload
42+
43+
It is not only when you POST but also whey you get a response.
44+
45+
Make a POST call with Content-Type: application/json
46+
```
47+
{
48+
"type":"sample type",
49+
"name":"sample name",
50+
"description":"sample description",
51+
"website":"sample website",
52+
"start_date":"sample start_date",
53+
"end_date":"sample end_date",
54+
"address":"sample address",
55+
"latitude":1.1,
56+
"longitude":1.1,
57+
"eventId":"sampleeventId"
58+
}
59+
```
60+
61+
Check also the response body.
62+
63+
### Schemas and Mixins
64+
65+
**It is all about the body**
66+
67+
Schema says what are the main service readable attributes: http://jsonschema.net/
68+
Mixins say that you can basically put whatever you want.
69+
70+
- Useful for validation
71+
- Gives a good overview of what data have to be provided
72+
73+
Make a POST call with Content-Type: application/json
74+
```
75+
{
76+
"type":"sample type",
77+
"name":"sample name"
78+
}
79+
```
80+
81+
### Response body and codes
82+
83+
All listed here: https://httpstatuses.com/
84+
85+
- 200
86+
- 400
87+
- 500
88+
89+
Make again a GET call to http://minerva.cfapps.io/events
90+
Make again a POST call with Content-Type: application/json
91+
```
92+
{
93+
"type":"sample type",
94+
"name":"sample name",
95+
"description":"sample description",
96+
"website":"sample website",
97+
"start_date":"sample start_date",
98+
"end_date":"sample end_date",
99+
"address":"sample address",
100+
"latitude":1.1,
101+
"longitude":1.1,
102+
"eventId":"sampleeventId"
103+
}
104+
```
105+
106+
The same call twice.
107+
108+
## Document using RAML or API Blueprint
109+
110+
RAML spec: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md
111+
Go to https://github.com/derberg/minerva/blob/master/service/api/api.raml
112+
113+
Develop with approach **API First** then you get:
114+
- API Reference: http://derberg.github.io/services/minerva/latest/index.html#ApiReference
115+
- API Console: http://derberg.github.io/services/minerva/latest/apiconsole.html
116+
- API Notebook: http://derberg.github.io/services/minerva/latest/index.html#Gettingconferenceeventsfor2016
117+
- API Client: http://derberg.github.io/services/minerva/latest/client.zip
118+
119+
Write it using:
120+
- API Designer: https://github.com/mulesoft/api-designer
121+
- Restlet Studio: https://studio.restlet.com/

‎docu/prerequisites.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Prerequisites
2+
3+
You need to have the following software/modules/applications installed on your computer to be able to complete all the steps of the workshop.
4+
5+
- Install Node.js and NPM: https://nodejs.org/en/download/ (both in one package) and then install:
6+
- [DocPad](http://docpad.org/) by calling in the terminal: `npm install -g npm`
7+
- [Gulp](http://gulpjs.com/) by calling in the terminal: `npm install -g gulp-cli`
8+
- Get GitHub account: https://github.com/
9+
- Install GitHub Desktop: https://desktop.github.com/ or GitHub CLI if you want to become a geek :)
10+
- Install some nice text editor like [Atom](https://atom.io/) or [Sublime Text](https://www.sublimetext.com/)

‎docu/using_docu_tool.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
## Configuring documentation publishing pipeline
2+
3+
First you need to fork some projects and configure them correctly to set up the documentation independent generation pipeline.
4+
5+
1. Fork the following repos (it means open the links and click on Fork button in the top right corner of the page):
6+
- API Doc portal template: https://github.com/hybris/docpad-skeleton-apidocs
7+
- Sample REST API microservice that we will be documenting: https://github.com/derberg/minerva
8+
- Sample registry that integrates the template and docu sources: https://github.com/derberg/apidoc-workshop-docu_registry
9+
10+
2. Configuration
11+
- Modify `chewieConfig.js` file in forked `docpad-skeleton-apidocs` repository. Change the `path` attribute:
12+
```
13+
path: process.env.REGISTRY_PATH || 'https://github.com/derberg/apidoc-workshop-docu_registry.git'
14+
```
15+
The git url must point to your forked `apidoc-workshop-docu_registry` repository.
16+
17+
- Modify `minerva.json` file in forked `apidoc-workshop-docu_registry` repository. Change the `location` attribute:
18+
```
19+
"location": "https://github.com/derberg/minerva"
20+
```
21+
The git url must point to your forked `minerva` repository.
22+
23+
## Start the API Doc portal locally
24+
25+
If configuration is completed you have to:
26+
27+
1. Clone your forked `docpad-skeleton-apidocs` repository,
28+
29+
2. Navigate to its local clone in the terminal,
30+
31+
3. Call the following command: `npm start`
32+
33+
4. Once the start is completed, open in the browser the following link: http://localhost:9778/
34+
35+
## Publishing to GitHub Pages
36+
37+
The easiest solution is to publish the API Doc portal on GitHub pages. Of course the generated API Doc portal files can be hosted on any other server as it is pure static content.
38+
39+
1. Create new repository with the following name: `your_github_username.github.io`. It must be public and initialized (You do it in UI during creation).
40+
41+
2. Modify `chewieConfig.js` file in forked `docpad-skeleton-apidocs` repository.
42+
- Change the `srcLocation` attribute:
43+
```
44+
srcLocation: 'https://github.com/derberg/derberg.github.io.git',
45+
```
46+
The git url must point to your newly created `your_github_username.github.io` repository.
47+
- Change the `docuUrl` attribute:
48+
```
49+
docuUrl: process.env.docuURL || 'http://derberg.github.io',
50+
```
51+
The page url must be the same as the name of your newly created `your_github_username.github.io` repository.
52+
53+
3. Modify `docpad.coffee` file in forked `docpad-skeleton-apidocs` repository. Change the `url` attribute:
54+
```
55+
environments:
56+
prod:
57+
templateData:
58+
site:
59+
url: "http://derberg.github.io"
60+
```
61+
It should point to the following url: `http://your_github_username.github.io`
62+
63+
4. Navigate to the local clone of `docpad-skeleton-apidocs` repository in the terminal
64+
65+
5. Call the following command: `npm run production`
66+
67+
6. Call the following command: `gulp pushResult`
68+
69+
7. Once the push is completed, open in the browser the following link: http://your_github_username.github.io

0 commit comments

Comments
 (0)