Skip to content

Commit c1e752b

Browse files
author
Alban Bailly
committed
Merge branch 'development'
2 parents e30e71f + dc34d83 commit c1e752b

16 files changed

+18075
-0
lines changed

‎Dockerfile

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
FROM ruby:2.3
2+
3+
COPY requirements.txt ./
4+
RUN apt-get update && apt-get install -y python3 python3-pip build-essential
5+
RUN pip3 install -r requirements.txt
6+
RUN gem install fpm
7+
8+
# I stole this from the linodemanager-builder to get yarn installed
9+
RUN curl -sL https://deb.nodesource.com/setup_8.x | bash -
10+
11+
RUN apt-get update \
12+
&& apt-get install -y nodejs
13+
14+
RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
15+
16+
RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
17+
18+
RUN apt-get update \
19+
&& apt-get install -y yarn
20+
# end stole config
21+
22+
COPY openapi-linter.py .
23+
COPY openapi.yaml .
24+
COPY build-docs.sh .
25+
COPY linode-docs.postinst .
26+
COPY linode-logo.svg .
27+
COPY linode-logo-white.svg .
28+
COPY redoc.standalone.js .
29+
COPY favicon.ico .
30+
COPY changelog/ .
31+
32+
CMD ["python", "openapi-linter.py", "openapi.yaml"]

‎Jenkinsfile

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
// vim: ft=groovy ts=2 sw=4 et
2+
def docs_version = 'UNKNOWN'
3+
def post_tag_commits = ''
4+
def repos = [master: 'linode-internal-apt-jessie-stg', develop: 'linode-internal-apt-jessie-dev', release: 'linode-internal-apt-jessie-testing']
5+
6+
environment {
7+
GA_ID = '{DEBCONF_CLOUD_GA_ID}'
8+
APP_ROOT = '{DEBCONF_APP_ROOT}'
9+
API_ROOT = '{DEBCONF_API_ROOT}'
10+
LOGIN_ROOT = '{DEBCONF_LOGIN_ROOT}'
11+
API_VERSION = 'v4' // used by docs - TODO can remove?
12+
BUILD_ENV = "${(env.BRANCH_NAME != 'master') ? env.BRANCH_NAME : '' }"
13+
// POST_TAG_COMMITS = "$post_tag_commits" - TODO can remove?
14+
}
15+
16+
node {
17+
def image;
18+
19+
stage('Checkout') {
20+
deleteDir()
21+
checkout scm
22+
sh "git fetch"
23+
24+
dir('ReDoc-customized') {
25+
checkout poll: false, scm: [
26+
$class: 'GitSCM',
27+
branches: [[name: 'development']],
28+
doGenerateSubmoduleConfigurations: false,
29+
credentialsId: "baker",
30+
extensions: [[
31+
$class: 'WipeWorkspace',
32+
], [
33+
$class: 'RelativeTargetDirectory',
34+
relativeTargetDir: 'ReDoc-customized',
35+
], [
36+
$class: 'CloneOption',
37+
noTags: false,
38+
]],
39+
userRemoteConfigs: [[
40+
refspec: "+refs/heads/*:refs/remotes/origin/*",
41+
url: '[email protected]:LinodeAPI/ReDoc-customized',
42+
]]
43+
]
44+
}
45+
}
46+
47+
stage('Build Docker') {
48+
BUILD_NAME = URLDecoder.decode(env.BUILD_TAG, "UTF-8").replaceAll("[^a-zA-Z0-9_.-]", "_")
49+
image = docker.build(BUILD_NAME.toLowerCase(), '.')
50+
image.inside() { c ->
51+
sh "cd ReDoc-customized/ReDoc-customized && yarn install && yarn bundle && yarn compile:cli && cd cli && yarn install && rm -r node_modules/redoc && ln -s ../.. node_modules/redoc"
52+
}
53+
}
54+
55+
stage ('Apply Substitutions') {
56+
version = sh(script: "git describe --tags --abbrev=0", returnStdout: true).trim()
57+
sh "sed -i -- 's|version: DEVELOPMENT|version: ${version}|' openapi.yaml"
58+
59+
replace_to = ''
60+
page_url = ''
61+
if (env.BRANCH_NAME == 'development') {
62+
replace_to = 'https://api.dev.linode.com/v4'
63+
page_url = 'https://developers.dev.linode.com'
64+
} else if (env.BRANCH_NAME ==~ /^release\/\d+\.\d+$/) {
65+
replace_to = 'https://api.testing.linode.com/v4'
66+
page_url = 'https://developers.testing.linode.com'
67+
} else {
68+
echo "Skipping environment-specific changes"
69+
}
70+
71+
if (replace_to != '') {
72+
echo "Applying environment-specific changes"
73+
image.inside() { c ->
74+
sh "sed -i -- 's|https://api.linode.com/v4|${replace_to}|' openapi.yaml"
75+
sh "sed -i -- 's|https://developers.linode.com|${page_url}|' openapi.yaml"
76+
}
77+
}
78+
}
79+
80+
stage ('OpenAPI Lint') {
81+
echo "Linting openapi.yaml"
82+
image.inside() { c ->
83+
sh "python3 openapi-linter.py openapi.yaml"
84+
}
85+
}
86+
87+
stage('Package Docs') {
88+
image.inside() { c ->
89+
sh "./build-docs.sh ${env.BRANCH_NAME}"
90+
archive '*.deb,*.changes,index.html,openapi.yaml,redoc.standalone.js'
91+
}
92+
}
93+
94+
if (env.BRANCH_NAME == 'master') {
95+
stage ('Apt-Repo') {
96+
sh "dupload --to linode-internal-apt-jessie-stg --nomail *.changes"
97+
}
98+
} else if (env.BRANCH_NAME == 'development') {
99+
stage('Apt-Repo') {
100+
sh "dupload --to linode-internal-apt-jessie-dev --nomail *.changes"
101+
}
102+
} else if (env.BRANCH_NAME ==~ /^release\/\d+\.\d+\.\d+$/) {
103+
stage('Apt-Repo') {
104+
sh "dupload --to linode-internal-apt-jessie-testing --nomail *.changes"
105+
}
106+
} else {
107+
echo "Branch '${env.BRANCH_NAME}' is not 'master', 'development', or a release branch. Skipping package upload."
108+
}
109+
}

‎README.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Linode OpenAPI 3
2+
3+
This is the Linode API OpenAPI 3 Schema
4+
5+
## Implementation
6+
7+
We are using [ReDoc](https://github.com/Rebilly/ReDoc) as the front end
8+
UI for our OpenAPI specification.
9+
10+
Additionally, we are taking advantage of ReDoc's support of
11+
[Vendor Extensions](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md)
12+
such as `x-logo` and `x-code-samples` for extended functionality.
13+
14+
A CSS file has also been added to the html page, to allow customization to the
15+
output.
16+
17+
## Requirements
18+
19+
Per the [Deployment
20+
Guidelines](https://github.com/Rebilly/ReDoc#deployment) of the ReDoc
21+
specification, ReDoc must be installed on the server via yarn or npm.
22+
23+
**yarn:**
24+
```
25+
yarn add redoc
26+
```
27+
28+
**NPM:**
29+
```
30+
npm install redoc --save
31+
```
32+
33+
## Development
34+
35+
Any http server serving this directory will work - simply reload the page to
36+
see changes. We're working on a nicer way to do this, but for now this should
37+
get you started:
38+
39+
```shell
40+
python3 -m http.server
41+
```
42+
43+
### Versioning
44+
45+
This specification is automatically versioned on build by Jenkins. The version
46+
presented in the spec is taken directly from the most recent annotated `git tag`
47+
to the build's `HEAD`. The package version appends the number of commits since
48+
the last tag to this number, separated by a hyphen. When making a new release
49+
you **must** tag the release with the correct semantic versioning-compliant
50+
version string so that all versions are populated appropriately.
51+
52+
### Updating Dependencies
53+
54+
The ReDoc version we are using in this repo is from a fork of the mainline ReDoc
55+
repo, found [here](https://github.com/dnknapp/ReDoc). This fork has custom
56+
modifications for Linode. In order to update the ReDoc we are using, clone that
57+
repo, rebase it's HEAD onto the latest upstream ReDoc (if desired), and run the
58+
following commands to generate a `redoc.standalone.js`:
59+
60+
```bash
61+
yarn
62+
yarn bundle
63+
cp bundles/redoc.standalone.js /path/to/linode-api-docs/
64+
```
65+
66+
This file _is_ committed to this repository, _is_ packaged with this repo's deb,
67+
and _is_ referenced with a relative link on the server.
68+
69+
## Spec Extensions
70+
71+
The OpenAPI specification supports vendor-specific extensions prefixed with an
72+
`x-` in the attribute name. The following extensions are created by Linode for
73+
use in our spec:
74+
75+
Attribute | Location | Type | Supported By | Explanation
76+
---|---|---|---|---
77+
`x-linode-filterable` | schema properties | boolean | | If `true`, indicates that this property may be included in an X-Filter header
78+
`x-linode-grant` | method | string | | The level of access a user must have in order to call this endpoint.
79+
`x-linode-cli-display` | schema properties | integer | linode-cli | If truthy, this property will be displayed in the Linode CLI. The numeric value determines the ordering of the displayed columns, left to right.
80+
`x-linode-cli-color` | schema properties | object | linode-cli | A mapping of possible property values to color codes understood by python's [colorclass module](https://pypi.python.org/pypi/colorclass). Must include a `default_`, used for any value that doesn't match one of the keys.
81+
`x-linode-cli-command` | path | string | linode-cli | The command group the methods of this path fall into when generating commands in the `linode-cli <command> <action>` format.
82+
`x-linode-cli-action` | method | string | linode-cli | The action this method will be mapped to when generating commands in the `linode-cli <command> <action>` format.
83+
`x-linode-cli-skip` | method | boolean | linode-cli | If true, the CLI will not expose this action.
84+
`x-linode-redoc-load-ids`| operation | boolean | If true, ReDoc will load this path and print a bulleted list of IDs. This only works on public collections.

‎build-docs.sh

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
#!/bin/bash
2+
set -x -e
3+
4+
##
5+
## Build the Docs
6+
##
7+
8+
BRANCHNAME=$1
9+
version_flag='~PR'
10+
11+
if [ $BRANCHNAME = 'development' ]; then
12+
version_flag='~dev'
13+
elif [[ $BRANCHNAME = release/* ]]; then
14+
version_flag='~test'
15+
elif [ $BRANCHNAME = 'master' ]; then
16+
version_flag=''
17+
fi
18+
19+
# if run from the vagrant project switch to linode-api-docs to mimic baker
20+
[[ -d "linode-api-docs" ]] && cd linode-api-docs
21+
22+
# run the static site builder
23+
chmod +x ReDoc-customized/ReDoc-customized/cli/index.js
24+
25+
./ReDoc-customized/ReDoc-customized/cli/index.js bundle openapi.yaml --options.hideDownloadButton=true --options.pathInMiddlePanel=true --options.expandResponses="200," --options.noAutoAuth=true --title='Linode API Documentation'
26+
27+
rm index.html
28+
mv redoc-static.html index.html
29+
30+
export HOME='/target'
31+
echo $HOME
32+
33+
version_number=$(git describe --tags --abbrev=0 | tr -d '[:space:]')
34+
version_extension=$(git log ${version_number}..HEAD --oneline | wc -l | tr -d '[:space:]')
35+
36+
version=${version_number}-${version_extension}${version_flag}
37+
38+
echo 'Building Debian Package'
39+
# index.html, openapi.yaml
40+
package_version="${version}"
41+
description='Linode API Docs'
42+
pkg_name="linode-docs"
43+
replaces="linode-alpha-docs,linode-vagrant-docs"
44+
45+
if [ -v BUILD_ENV -a -n "${BUILD_ENV}" ]; then
46+
description="${description} ($BUILD_ENV)"
47+
package_version="${version}~${BUILD_ENV}${commit_num:-0}"
48+
fi
49+
50+
fpm -s dir -t deb -n "${pkg_name}" -v "${version_number}" --iteration "${version_extension}${version_flag}" \
51+
-x Vagrantfile -x Dockerfile -x build.sh -x \*.deb -x \*.changes -x .git -x .vagrant \
52+
--vendor Linode --url https://github.com/linode/linode-api-docs \
53+
--description "${description}" -m [email protected] \
54+
-a all --prefix /usr/share/linode-docs/templates/ \
55+
--after-install linode-docs.postinst \
56+
--replaces "${replaces}" -- \
57+
index.html openapi.yaml linode-logo.svg redoc.standalone.js \
58+
favicon.ico changelog/index.html changelog/changelog-style.css linode-logo-white.svg
59+
60+
outfile="$(ls -t ${pkg_name}*_all.deb | head -1)"
61+
sha1=$(sha1sum ${outfile})
62+
sha256=$(sha256sum ${outfile})
63+
md5=$(md5sum ${outfile})
64+
size=$(stat -c%s "$outfile")
65+
66+
(
67+
cat <<EOF
68+
Format: 1.8
69+
Date: $(date -R)
70+
Source: ${pkg_name}
71+
Binary: ${pkg_name}
72+
Architecture: all
73+
Version: ${version}
74+
Distribution: linode-jessie-dev
75+
Urgency: low
76+
Maintainer: Linode Operations <[email protected]>
77+
Changed-By: Linode Developers <[email protected]>
78+
Description:
79+
${description}
80+
Changes:
81+
${pkg_name} (${package_version}) linode-jessie-dev; urgency=low
82+
.
83+
* $(git log -1 --pretty=format:%s)
84+
Checksums-Sha1:
85+
${sha1% *} ${size} ${outfile}
86+
Checksums-Sha256:
87+
${sha256% *} ${size} ${outfile}
88+
Files:
89+
${md5% *} ${size} linode-jessie-dev/api extra ${outfile}
90+
EOF
91+
) > ${outfile::-3}changes

‎changelog/changelog-style.css

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
html {
2+
box-sizing: border-box;
3+
}
4+
5+
body {
6+
flex-direction: column;
7+
flex-grow: 1;
8+
color: #000;
9+
background: #fff;
10+
font-family: 'Lato',sans-serif;
11+
font-weight: 400;
12+
font-size: 16px;
13+
line-height: 1.5;
14+
padding-left: 2em;
15+
}
16+
17+
header {
18+
background: #323232;
19+
}
20+
21+
.release-header {
22+
display: block;
23+
color: #ffffff;
24+
font-weight: normal;
25+
margin-top: 2em;
26+
margin-bottom: 1em;
27+
background: #3bb878;
28+
padding: 0.2em 0.25em 0.25em 0.25em;
29+
height: 32px;
30+
}
31+
32+
.release-header .release-version {
33+
font-size: 0.8em;
34+
float: right;
35+
vertical-align: middle;
36+
position: relative;
37+
top: 3px;
38+
}
39+
40+
h3 {
41+
font-size: 1.2em;
42+
}
43+
44+
.content-wrap {
45+
max-width: 970px;
46+
margin: 0 auto;
47+
padding: 0 15px;
48+
}
49+
50+
.main {
51+
flex-grow: 1;
52+
display: flex;
53+
flex-direction: column;
54+
}
55+
56+
.navbar {
57+
display: flex;
58+
justify-content: space-between;
59+
height: 57px;
60+
}
61+
62+
.navbar-logo {
63+
height: 46px;
64+
padding: 6px 0;
65+
vertical-align: middle;
66+
}
67+
68+
.navbar-wrap {
69+
display: flex;
70+
justify-content: space-between;
71+
}

0 commit comments

Comments
 (0)