Skip to content

Commit 8a6d564

Browse files
jcenturionjcenturion
committed
Start showing security scheme data on documentation
1 parent 8d0230a commit 8a6d564

File tree

9 files changed

+382
-84
lines changed

9 files changed

+382
-84
lines changed

‎dist/examples/leagues.raml‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,7 @@ securitySchemes:
1212
type: Digest Authentication
1313
- oauth_2_0:
1414
description: |
15-
OAuth2 is a protocol that lets external apps request authorization to private
16-
details in a user's GitHub account without getting their password. This is
17-
preferred over Basic Authentication because tokens can be limited to specific
18-
types of data, and can be revoked by users at any time.
15+
OAuth2 is a protocol that lets external apps request authorization to private details in a user's GitHub account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.
1916
type: OAuth 2.0
2017
describedBy:
2118
headers:
@@ -34,8 +31,8 @@ securitySchemes:
3431
404:
3532
description: Unauthorized
3633
settings:
37-
authorizationUri: https://github.com/login/oauth/authorize
38-
accessTokenUri: https://github.com/login/oauth/access_token
34+
authorizationUri: https://leagues.com/login/oauth/authorize
35+
accessTokenUri: https://leagues.com/login/oauth/access_token
3936
authorizationGrants: [ code, credentials, owner ]
4037
scopes:
4138
- "user"
@@ -45,8 +42,10 @@ securitySchemes:
4542
describedBy:
4643
headers:
4744
auth:
45+
type: string
4846
queryParameters:
4947
access_token:
48+
type: string
5049
- custom_scheme_2:
5150
type: x-custom
5251
describedBy:

‎dist/scripts/api-console.js‎

Lines changed: 119 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,29 @@
125125
templateUrl: 'directives/documentation.tpl.html',
126126
replace: true,
127127
controller: function($scope) {
128+
var defaultSchemaKey = Object.keys($scope.securitySchemes).sort()[0];
129+
var defaultSchema = $scope.securitySchemes[defaultSchemaKey];
130+
128131
$scope.markedOptions = RAML.Settings.marked;
132+
$scope.documentationSchemeSelected = defaultSchema;
133+
134+
$scope.isSchemeSelected = function isSchemeSelected(scheme) {
135+
return scheme.id === $scope.documentationSchemeSelected.id;
136+
};
137+
138+
$scope.selectDocumentationScheme = function selectDocumentationScheme(scheme) {
139+
$scope.documentationSchemeSelected = scheme;
140+
};
141+
142+
$scope.schemaSettingsDocumentation = function schemaSettingsDocumentation(settings) {
143+
var doc = settings;
144+
145+
if (typeof settings === 'object') {
146+
doc = settings.join(', ');
147+
}
148+
149+
return doc;
150+
}
129151

130152
$scope.unique = function (arr) {
131153
return arr.filter (function (v, i, a) { return a.indexOf (v) === i; });
@@ -185,50 +207,52 @@
185207
$scope.parameterDocumentation = function (parameter) {
186208
var result = '';
187209

188-
if (parameter.required) {
189-
result += 'required, ';
190-
}
210+
if (parameter) {
211+
if (parameter.required) {
212+
result += 'required, ';
213+
}
191214

192-
if (parameter.enum) {
193-
var enumValues = $scope.unique(parameter.enum);
215+
if (parameter.enum) {
216+
var enumValues = $scope.unique(parameter.enum);
194217

195-
if (enumValues.length > 1) {
196-
result += 'one of ';
197-
}
218+
if (enumValues.length > 1) {
219+
result += 'one of ';
220+
}
198221

199-
result += '(' + enumValues.join(', ') + ')';
222+
result += '(' + enumValues.join(', ') + ')';
200223

201-
} else {
202-
result += parameter.type;
203-
}
224+
} else {
225+
result += parameter.type || '';
226+
}
204227

205-
if (parameter.pattern) {
206-
result += ' matching ' + parameter.pattern;
207-
}
228+
if (parameter.pattern) {
229+
result += ' matching ' + parameter.pattern;
230+
}
208231

209-
if (parameter.minLength && parameter.maxLength) {
210-
result += ', ' + parameter.minLength + '-' + parameter.maxLength + ' characters';
211-
} else if (parameter.minLength && !parameter.maxLength) {
212-
result += ', at least ' + parameter.minLength + ' characters';
213-
} else if (parameter.maxLength && !parameter.minLength) {
214-
result += ', at most ' + parameter.maxLength + ' characters';
215-
}
232+
if (parameter.minLength && parameter.maxLength) {
233+
result += ', ' + parameter.minLength + '-' + parameter.maxLength + ' characters';
234+
} else if (parameter.minLength && !parameter.maxLength) {
235+
result += ', at least ' + parameter.minLength + ' characters';
236+
} else if (parameter.maxLength && !parameter.minLength) {
237+
result += ', at most ' + parameter.maxLength + ' characters';
238+
}
216239

217240

218-
if (parameter.minimum && parameter.maximum) {
219-
result += ' between ' + parameter.minimum + '-' + parameter.maximum;
220-
} else if (parameter.minimum && !parameter.maximum) {
221-
result += ' ≥ ' + parameter.minimum;
222-
} else if (parameter.maximum && !parameter.minimum) {
223-
result += ' ≤ ' + parameter.maximum;
224-
}
241+
if (parameter.minimum && parameter.maximum) {
242+
result += ' between ' + parameter.minimum + '-' + parameter.maximum;
243+
} else if (parameter.minimum && !parameter.maximum) {
244+
result += ' ≥ ' + parameter.minimum;
245+
} else if (parameter.maximum && !parameter.minimum) {
246+
result += ' ≤ ' + parameter.maximum;
247+
}
225248

226-
if (parameter.repeat) {
227-
result += ', repeatable';
228-
}
249+
if (parameter.repeat) {
250+
result += ', repeatable';
251+
}
229252

230-
if (parameter['default']) {
231-
result += ', default: ' + parameter['default'];
253+
if (parameter['default']) {
254+
result += ', default: ' + parameter['default'];
255+
}
232256
}
233257

234258
return result;
@@ -1090,6 +1114,7 @@
10901114
$scope.currentSchemeType = defaultSchema.type;
10911115
$scope.currentScheme = defaultSchema.id;
10921116
$scope.currentProtocol = $scope.raml.protocols[0];
1117+
$scope.documentationSchemeSelected = defaultSchema;
10931118
});
10941119

10951120
$scope.cancelRequest = function () {
@@ -1237,6 +1262,8 @@
12371262
cleanSchemeMetadata($scope.methodInfo.headers.plain, $scope.context.headers);
12381263
cleanSchemeMetadata($scope.methodInfo.queryParameters, $scope.context.queryParameters);
12391264

1265+
$scope.documentationSchemeSelected = $scope.securitySchemes[name];
1266+
12401267
if (type === 'x-custom') {
12411268
if (!$scope.methodInfo.headers.plain) {
12421269
$scope.methodInfo.headers.plain = {};
@@ -5061,7 +5088,7 @@ angular.module('ramlConsoleApp').run(['$templateCache', function($templateCache)
50615088
" <section class=\"raml-console-resource-section\" id=\"docs-headers\" ng-if=\"methodInfo.headers.plain\">\n" +
50625089
" <h3 class=\"raml-console-resource-heading-a\">Headers</h3>\n" +
50635090
"\n" +
5064-
" <div class=\"raml-console-resource-param\" ng-repeat=\"header in methodInfo.headers.plain\">\n" +
5091+
" <div class=\"raml-console-resource-param\" ng-repeat=\"header in methodInfo.headers.plain\" ng-if=\"!header[0].isFromSecurityScheme\">\n" +
50655092
" <h4 class=\"raml-console-resource-param-heading\">{{header[0].displayName}}<span class=\"raml-console-resource-param-instructional\">{{parameterDocumentation(header[0])}}</span></h4>\n" +
50665093
"\n" +
50675094
" <p marked=\"header[0].description\" opts=\"markedOptions\"></p>\n" +
@@ -5075,7 +5102,7 @@ angular.module('ramlConsoleApp').run(['$templateCache', function($templateCache)
50755102
" <section class=\"raml-console-resource-section\" id=\"docs-query-parameters\" ng-if=\"methodInfo.queryParameters\">\n" +
50765103
" <h3 class=\"raml-console-resource-heading-a\">Query Parameters</h3>\n" +
50775104
"\n" +
5078-
" <div class=\"raml-console-resource-param\" ng-repeat=\"queryParam in methodInfo.queryParameters\">\n" +
5105+
" <div class=\"raml-console-resource-param\" ng-repeat=\"queryParam in methodInfo.queryParameters\" ng-if=\"!queryParam[0].isFromSecurityScheme\">\n" +
50795106
" <h4 class=\"raml-console-resource-param-heading\">{{queryParam[0].displayName}}<span class=\"raml-console-resource-param-instructional\">{{parameterDocumentation(queryParam[0])}}</span></h4>\n" +
50805107
"\n" +
50815108
" <p marked=\"queryParam[0].description\" opts=\"markedOptions\"></p>\n" +
@@ -5086,6 +5113,62 @@ angular.module('ramlConsoleApp').run(['$templateCache', function($templateCache)
50865113
" </div>\n" +
50875114
" </section>\n" +
50885115
"\n" +
5116+
" <section class=\"raml-console-resource-section raml-console-documentation-schemes\">\n" +
5117+
" <h3 class=\"raml-console-resource-heading-a\">Security Schemes</h3>\n" +
5118+
" <ol class=\"raml-console-documentation-security-scheme\">\n" +
5119+
" <li class=\"raml-console-documentation-scheme\" ng-class=\"{'raml-console-is-active':isSchemeSelected(value)}\" ng-click=\"selectDocumentationScheme(value)\" ng-repeat=\"(key, value) in securitySchemes\">{{value.name}}</li>\n" +
5120+
" </ol>\n" +
5121+
"\n" +
5122+
" <p ng-if\"documentationSchemeSelected.description\" marked=\"documentationSchemeSelected.description\" opts=\"markedOptions\"></p>\n" +
5123+
"\n" +
5124+
" <section class=\"raml-console-resource-section raml-console-scheme-headers\" ng-if=\"documentationSchemeSelected.describedBy.headers\">\n" +
5125+
" <h4 class=\"raml-console-resource-heading-a\">Headers</h4>\n" +
5126+
"\n" +
5127+
" <div class=\"raml-console-resource-param\" ng-repeat=\"(key, header) in documentationSchemeSelected.describedBy.headers\">\n" +
5128+
" <h4 class=\"raml-console-resource-param-heading\">{{key}}<span class=\"raml-console-resource-param-instructional\">{{parameterDocumentation(header)}}</span></h4>\n" +
5129+
"\n" +
5130+
" <p marked=\"header.description\" opts=\"markedOptions\"></p>\n" +
5131+
"\n" +
5132+
" <p ng-if=\"header.example\">\n" +
5133+
" <span class=\"raml-console-resource-param-example\"><b>Example:</b> {{header.example}}</span>\n" +
5134+
" </p>\n" +
5135+
" </div>\n" +
5136+
" </section>\n" +
5137+
"\n" +
5138+
" <section class=\"raml-console-resource-section raml-console-scheme-query-parameters\" ng-if=\"documentationSchemeSelected.describedBy.queryParameters\">\n" +
5139+
" <h4 class=\"raml-console-resource-heading-a\">Query Parameters</h4>\n" +
5140+
"\n" +
5141+
" <div class=\"raml-console-resource-param\" ng-repeat=\"(key, queryParameter) in documentationSchemeSelected.describedBy.queryParameters\">\n" +
5142+
" <h4 class=\"raml-console-resource-param-heading\">{{key}}<span class=\"raml-console-resource-param-instructional\">{{parameterDocumentation(queryParameter)}}</span></h4>\n" +
5143+
"\n" +
5144+
" <p marked=\"queryParameter.description\" opts=\"markedOptions\"></p>\n" +
5145+
"\n" +
5146+
" <p ng-if=\"queryParameter.example\">\n" +
5147+
" <span class=\"raml-console-resource-param-example\"><b>Example:</b> {{queryParameter.example}}</span>\n" +
5148+
" </p>\n" +
5149+
" </div>\n" +
5150+
" </section>\n" +
5151+
"\n" +
5152+
" <section class=\"raml-console-resource-section raml-console-scheme-responses\" ng-if=\"documentationSchemeSelected.describedBy.responses\">\n" +
5153+
" <h4 class=\"raml-console-resource-heading-a\">Responses</h4>\n" +
5154+
"\n" +
5155+
" <div class=\"raml-console-resource-param\" ng-repeat=\"(code, info) in documentationSchemeSelected.describedBy.responses\">\n" +
5156+
" <h4 class=\"raml-console-resource-param-heading\">{{code}}</h4>\n" +
5157+
" <p marked=\"info.description\" opts=\"markedOptions\"></p>\n" +
5158+
" </div>\n" +
5159+
" </section>\n" +
5160+
"\n" +
5161+
" <section class=\"raml-console-resource-section raml-console-scheme-settings\" ng-if=\"documentationSchemeSelected.settings\">\n" +
5162+
" <h4 class=\"raml-console-resource-heading-a\">Settings</h4>\n" +
5163+
"\n" +
5164+
" <div class=\"raml-console-resource-param\" ng-repeat=\"(key, config) in documentationSchemeSelected.settings\">\n" +
5165+
" <h4 class=\"raml-console-resource-param-heading\">{{key}}</h4>\n" +
5166+
" <p>{{schemaSettingsDocumentation(config)}}</p>\n" +
5167+
" </div>\n" +
5168+
" </section>\n" +
5169+
" </section>\n" +
5170+
"\n" +
5171+
"\n" +
50895172
" <section class=\"raml-console-resource-section\" ng-if=\"methodInfo.body\">\n" +
50905173
" <h3 class=\"raml-console-resource-heading-a\">\n" +
50915174
" Body\n" +

‎dist/styles/api-console-dark-theme.css‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4130,6 +4130,52 @@ span.raml-console-side-bar-required-field {
41304130
cursor: pointer;
41314131
}
41324132

4133+
.raml-console-documentation-schemes p {
4134+
font-size: 13px;
4135+
}
4136+
4137+
.raml-console-documentation-schemes .raml-console-scheme-headers,
4138+
.raml-console-documentation-schemes .raml-console-scheme-query-parameters,
4139+
.raml-console-documentation-schemes .raml-console-scheme-settings,
4140+
.raml-console-documentation-schemes .raml-console-scheme-responses {
4141+
margin-top: 0;
4142+
}
4143+
4144+
.raml-console-documentation-schemes .raml-console-scheme-headers h4,
4145+
.raml-console-documentation-schemes .raml-console-scheme-query-parameters h4,
4146+
.raml-console-documentation-schemes .raml-console-scheme-settings h4,
4147+
.raml-console-documentation-schemes .raml-console-scheme-responses h4 {
4148+
font-size: 12px;
4149+
margin-bottom: 7px;
4150+
}
4151+
4152+
.raml-console-documentation-security-scheme {
4153+
list-style-type: none;
4154+
padding-left: 0;
4155+
margin-bottom: 18px;
4156+
}
4157+
4158+
.raml-console-documentation-security-scheme .raml-console-documentation-scheme {
4159+
display: inline-block;
4160+
padding: 2px 8px;
4161+
border: 1px solid #d5d7d9;
4162+
border-radius: 5px;
4163+
background: #e3e4e6;
4164+
color: #333;
4165+
font-size: 12px;
4166+
cursor: pointer;
4167+
margin-right: 5px;
4168+
}
4169+
4170+
.raml-console-documentation-security-scheme .raml-console-documentation-scheme:hover {
4171+
background: #d6d7da;
4172+
}
4173+
4174+
.raml-console-documentation-security-scheme .raml-console-is-active {
4175+
background: #bbbbbb;
4176+
color: #333;
4177+
}
4178+
41334179
.raml-console-document-heading {
41344180
cursor: pointer;
41354181
}

‎dist/styles/api-console-light-theme.css‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4130,6 +4130,52 @@ span.raml-console-side-bar-required-field {
41304130
cursor: pointer;
41314131
}
41324132

4133+
.raml-console-documentation-schemes p {
4134+
font-size: 13px;
4135+
}
4136+
4137+
.raml-console-documentation-schemes .raml-console-scheme-headers,
4138+
.raml-console-documentation-schemes .raml-console-scheme-query-parameters,
4139+
.raml-console-documentation-schemes .raml-console-scheme-settings,
4140+
.raml-console-documentation-schemes .raml-console-scheme-responses {
4141+
margin-top: 0;
4142+
}
4143+
4144+
.raml-console-documentation-schemes .raml-console-scheme-headers h4,
4145+
.raml-console-documentation-schemes .raml-console-scheme-query-parameters h4,
4146+
.raml-console-documentation-schemes .raml-console-scheme-settings h4,
4147+
.raml-console-documentation-schemes .raml-console-scheme-responses h4 {
4148+
font-size: 12px;
4149+
margin-bottom: 7px;
4150+
}
4151+
4152+
.raml-console-documentation-security-scheme {
4153+
list-style-type: none;
4154+
padding-left: 0;
4155+
margin-bottom: 18px;
4156+
}
4157+
4158+
.raml-console-documentation-security-scheme .raml-console-documentation-scheme {
4159+
display: inline-block;
4160+
padding: 2px 8px;
4161+
border: 1px solid #d5d7d9;
4162+
border-radius: 5px;
4163+
background: #e3e4e6;
4164+
color: #333;
4165+
font-size: 12px;
4166+
cursor: pointer;
4167+
margin-right: 5px;
4168+
}
4169+
4170+
.raml-console-documentation-security-scheme .raml-console-documentation-scheme:hover {
4171+
background: #d6d7da;
4172+
}
4173+
4174+
.raml-console-documentation-security-scheme .raml-console-is-active {
4175+
background: #bbbbbb;
4176+
color: #333;
4177+
}
4178+
41334179
.raml-console-document-heading {
41344180
cursor: pointer;
41354181
}

0 commit comments

Comments
 (0)