Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-01-25 00:07:47 +01:00
Code Issues Projects Releases Wiki Activity

fix: Swagger to redoc (#678)

Browse Source 
Co-authored-by: Ivar Conradi Østhus <ivarconr@gmail.com>
This commit is contained in:
gazconroy 2021-01-06 13:24:39 +00:00 committed by GitHub
parent 14ee8fcdcf
commit 86b2a4f5ad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 51 additions and 1835 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
docs/api/oas/index.html
View File

@ -1,77 +1,43 @@
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html> <!DOCTYPE html>
<html lang="en"> <html>
<head> <head>
<meta charset="UTF-8"> <title>ReDoc</title>
<title>Unleash Open API</title> <!-- needed for adaptive design -->
<link rel="stylesheet" href="theme-material.css"> <meta charset="utf-8"/>
<!-- Material design styles from ostranme.github.io/swagger-ui-themes <meta name="viewport" content="width=device-width, initial-scale=1">
Original follows <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css" > -->
<link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" /> <!--
<link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" /> ReDoc doesn't change outer page styles
-->
<style> <style>
html body {
{ margin: 0;
box-sizing: border-box; padding: 0;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body
{
margin:0;
background: #fafafa;
}
.topbar-wrapper img {
content: url(https://unleash.github.io/img/logo-inverted.png);
}
.swagger-ui .topbar .download-url-wrapper .download-url-button {
background-color: #3f51b5 !important;
}
.swagger-ui .topbar .download-url-wrapper input[type=text] {
border-color: #3f51b5 !important;
} }
</style> </style>
</head> </head>
<body> <body>
<div id="swagger-ui"></div>
<script src="./swagger-ui-bundle.js" charset="UTF-8"> </script> <!-- ### DEFAULT REDOC - NO 'TRY' FEATURE -->
<script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script> <!-- <redoc spec-url='openapi.yaml'></redoc> -->
<script> <!-- <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> -->
window.onload = function() { <!-- ### REDOC WITH SWAGGER UI'S 'TRY' FEATURE WITHIN REDOC -->
// Begin Swagger UI call region <!-- From https://github.com/wll8/redoc-try -->
const ui = SwaggerUIBundle({ <div id="redoc-container"></div>
url: "openapi.yaml", <script src="//cdn.jsdelivr.net/npm/redoc@2.0.0-rc.28/bundles/redoc.standalone.min.js"> </script>
dom_id: '#swagger-ui', <script src="//cdn.jsdelivr.net/gh/wll8/redoc-try/dist/try.js"></script>
defaultModelsExpandDepth: -1, <script>
operationsSorter: "alpha", var unleashRedoc = {
deepLinking: true, openApi: `openapi.yaml`,
presets: [ onlySwagger: false, // Set to true to switch to Swagger UI output
SwaggerUIBundle.presets.apis, tryText: `Try it out`, // Try button text
SwaggerUIStandalonePreset trySwaggerInApi: false, // Do not display Swagger debugging window under API
], redocOptions: {hideDownloadButton: true, noAutoAuth: true, sortPropsAlphabetically: true, theme: {spacing: {sectionVertical: '5px',}},},
plugins: [ swaggerOptions: {dom_id: `#swagger-ui`},
SwaggerUIBundle.plugins.DownloadUrl }
], initTry(unleashRedoc);
layout: "StandaloneLayout" </script>
})
// End Swagger UI call region
window.ui = ui
}
</script>
</body> </body>
</html> </html>

43
docs/api/oas/openapi.yaml
View File

@ -1,7 +1,3 @@
# COMMUNITY QUESTIONS
# About /client/metrics
# Client variants schema. What are the various weight types and what do they do? Is there a finite list of types for the payload (or is that entirely client-dependent)?
# Is the client variant schema different to the admin schema? The markdown docs indicate that's the case
# TESTING # TESTING
# QA team test cases. Test code exists but were these based on a list of steps required to produce a result? # QA team test cases. Test code exists but were these based on a list of steps required to produce a result?
# Are there any real-world users of Unleash who are happy to read and test the Open API specification and make suggestions for improvement? Would they be happy to screen-record what they are doing (how they use the API will give invaluable insights)? # Are there any real-world users of Unleash who are happy to read and test the Open API specification and make suggestions for improvement? Would they be happy to screen-record what they are doing (how they use the API will give invaluable insights)?
@ -11,10 +7,6 @@
# Move responses to root responses section in components (from schema section) # Move responses to root responses section in components (from schema section)
# Issues with rendering as nested externaldocs from Swagger UI. See GET /admin/feature-types. Not an issue in other tools (see redoc.html) # Issues with rendering as nested externaldocs from Swagger UI. See GET /admin/feature-types. Not an issue in other tools (see redoc.html)
# Other candidates for $ref: createdAt, lastSeen/updatedAt, instanceId, appName/appNamePath, sdkVersion, feature toggle type titles, enabled, stale, weight # Other candidates for $ref: createdAt, lastSeen/updatedAt, instanceId, appName/appNamePath, sdkVersion, feature toggle type titles, enabled, stale, weight
# SWAGGER UI
# Does not expand all schemas. A SwaggerUIBundle setting?
# REDOC
# 'Try it out' instructions do not apply since the free version of Redoc has no such feature. The Postman button helps here...
# STYLE # STYLE
# Add style guide MD. UK/US = US, Newspaper/Movie, Plurals. &. What 's the closest match for Unleash? http://apistylebook.com/design/guidelines/ # Add style guide MD. UK/US = US, Newspaper/Movie, Plurals. &. What 's the closest match for Unleash? http://apistylebook.com/design/guidelines/
# OAS styler - Only use backticks for code samples and API paths. Use bold for schema items and italic for schema item settings # OAS styler - Only use backticks for code samples and API paths. Use bold for schema items and italic for schema item settings
@ -49,22 +41,20 @@ info:
description: |- description: |-
Unleash is an open source feature flag and toggle system for all your applications and services. Unleash is an open source feature flag and toggle system for all your applications and services.
## Try it out # Try it out
## Try it in your browser
Once you have [set your Unleash server up](https://unleash.github.io/docs/getting_started), you can test the API from inside your browser. The following assumes the server is running on localhost:4242. Once you have [set your Unleash server up](https://unleash.github.io/docs/getting_started), you can test the API from inside your browser. The following assumes the server is running on localhost:4242.
The following 'endpoints' (such as `GET /admin/metrics/applications`) provide reference documentation for the Unleash REST API. To try out API calls: The following 'endpoints' (such as `GET /admin/metrics/applications`) provide reference documentation for the Unleash REST API. To try out API calls:
1. Expand an endpoint 1. Navigate to an endpoint
2. Click **Try it out** 2. Click **Try it out** - in the right-hand (black) panel
3. Customize the **Request body** and/or **Parameters**. 3. Customize the **Request body** and/or **Parameters**.
4. Click **Execute**. 4. Click **Execute**.
You will see the cURL request submitted to the API server and the corresponding response. You will see the cURL request submitted to the API server and the corresponding response.
## Try it in Redoc
Unlike [the default version](index.html) of the API, the [Redoc version](redoc.html) doesn't have a 'try it out' facility but gives a clearer display of the schemas (which you might prefer)
## Try it in Postman ## Try it in Postman
Alternatively, you can test the API in [Postman](https://app.getpostman.com/run-collection/8552ddcd4cc9fc012548) Alternatively, you can test the API in [Postman](https://app.getpostman.com/run-collection/8552ddcd4cc9fc012548)
@ -107,8 +97,8 @@ paths:
$ref: '#/components/schemas/401' $ref: '#/components/schemas/401'
/client/metrics: /client/metrics:
post: post:
summary: Register a metrics payload with a timed bucket. summary: Register a metrics *bucket*.
description: ??? description: A *bucket* is a set of metrics data that tells you how often a Feature Toggle was enabled or disabled during a specified period of time
operationId: sendMetrics operationId: sendMetrics
requestBody: requestBody:
required: true required: true
@ -506,7 +496,7 @@ paths:
'/admin/archive/revive/{featureName}': '/admin/archive/revive/{featureName}':
post: post:
summary: Un-archive a Feature Toggle summary: Un-archive a Feature Toggle
description: The Feature Toggle had been previously deleted description: Restore a Feature Toggle that has been previously deleted
operationId: reviveFeatureToggle operationId: reviveFeatureToggle
tags: tags:
- Archive - Archive
@ -1038,6 +1028,7 @@ components:
x-tags: x-tags:
- Responses - Responses
metricsPayloadSchema: metricsPayloadSchema:
description: A *bucket* of metrics data that tells you how often a Feature Toggle was enabled or disabled during a specified period of time
type: object type: object
required: required:
- appName - appName
@ -1062,11 +1053,11 @@ components:
properties: properties:
start: start:
type: string type: string
description: 'The start time of something (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' description: 'The start time for your metrics (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))'
example: '2020-12-08T13:50:00.000Z' example: '2020-12-08T13:50:00.000Z'
stop: stop:
type: string type: string
description: 'The end time of that same thing (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))' description: 'The end time for your metrics (in [ISO8601 format](https://www.w3.org/TR/NOTE-datetime))'
example: '2020-12-08T13:55:00.000Z' example: '2020-12-08T13:55:00.000Z'
toggles: toggles:
$ref: '#/components/schemas/toggleSchema' $ref: '#/components/schemas/toggleSchema'
@ -1079,6 +1070,7 @@ components:
- metricsCount - metricsCount
properties: properties:
yesno: yesno:
description: Was a Feature Toggle enabled (yes) or disabled (no)?
type: object type: object
properties: properties:
yesorno: yesorno:
@ -1088,6 +1080,7 @@ components:
- 'no' - 'no'
example: 'yes' example: 'yes'
metricsCount: metricsCount:
description: The number of times a Feature Toggle was enabled or disabled during the specified start and end time
type: object type: object
properties: properties:
count: count:
@ -1452,7 +1445,10 @@ components:
weight: weight:
description: |- description: |-
A number between 0 and 1,000. A number between 0 and 1,000.
The client SDK will summarize all variant weights, hash the number and divide the users among them. The distribution will be according to the weight as a fraction of the sum of weight. The client SDK will allocate traffic to each variant based on this weighting (as a fraction of the sum of all variant weights).
**Examples**
- You have four variants, each with a weight of 1000. The SDK will distribute traffic evenly: 25% each
- You have two variants, one with a weight of 100 and one with a weight of 900. The SDK will send 90% of traffic to the variant with a weight of 900
type: number type: number
example: 20 example: 20
weightType: weightType:
@ -1461,7 +1457,7 @@ components:
example: 'variable' example: 'variable'
payload: payload:
type: object type: object
description: 'Optional data associated with the variant, consisting of a *type/value* pair' description: 'Optional data associated with the variant, consisting of a *type/value* pair (as defined in the SDK)'
properties: properties:
type: type:
type: string type: string
@ -1497,9 +1493,6 @@ components:
createdAt: createdAt:
type: string type: string
minLength: 1 minLength: 1
lastSeenAt:
type: string
minLength: 1
x-tags: x-tags:
- Responses - Responses
200-events: 200-events:

24
docs/api/oas/redoc.html
View File

@ -1,24 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='openapi.yaml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>

1719
docs/api/oas/theme-material.css
View File

File diff suppressed because it is too large Load Diff