Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Bundle VC-API and provide UX on API Docs #270

Merged
merged 11 commits into from
Mar 20, 2022
Merged

Bundle VC-API and provide UX on API Docs #270

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
c68cb2b
feat: add initial bundling of api
mprorock Mar 13, 2022
2a53cae
feat: add stubs for common openapi ux
mprorock Mar 13, 2022
01db86f
chore: stub in api viewers
mprorock Mar 13, 2022
594fc5c
chore: update build script
mprorock Mar 13, 2022
50b20ea
chore: add initial tags
mprorock Mar 13, 2022
4298e47
chore: update bundling and outputs
mprorock Mar 13, 2022
cfe28f3
chore: specify dev dependencies
mprorock Mar 13, 2022
4adeeb1
feat: add gh workflow to build and deploy docs
mprorock Mar 13, 2022
19c3bff
doc: update readme for npm build
mprorock Mar 13, 2022
ca74e07
chore: remove any auto-gen-files
mprorock Mar 13, 2022
9df6b57
chore: update gitignore for auto-gen files
mprorock Mar 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/workflows/generate-docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# API Documentation for VC-API
name: "Build and Publish VC-API Docs"

on:
push:
branches: [ main ]

jobs:
prepare:
name: "Prepare OAS Artifacts"
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: "Build Docs"
uses: actions/setup-node@v1
with:
node-version: '16.x'
- run: npm install -g redoc-cli
- run: npm install -g @redocly/openapi-cli
- run: npm install
- run: npm run build
- name: "Upload Generated Docs"
uses: actions/upload-artifact@v2
with:
name: generated-docs
path: docs

deploy:
name: "Deploy Docs to GitHub Pages"
needs: prepare
runs-on: ubuntu-latest
steps:
- name: "Download Generated Docs"
uses: actions/download-artifact@v2
with:
name: generated-docs

- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ${{steps.download.outputs.download-path}}

6 changes: 5 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
node_modules

docs/test-suite
docs/test-suite

package-lock.json
api/bundles/*.yml
api/*.yaml
16 changes: 16 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,22 @@ This entails:
- Minutes are scribed by volunteers from the group and sent to the CCG mailing
list for review.

### Development

To assemble bundled yamls, as well as a master bundel of all definitions
run the following:

```bash
npm run build
```

This will generate the following files:

- `api/vc-api.yaml` a master file with all specifications rolled into one
- `api/bundles/issuer.yml` issuer endpoints bundled with no external refs
- `api/bundles/verifier.yml` verifier endpoints bundled with no external refs
- `api/bundles/holder.yml` holder endpoints bundled with no external refs
Comment on lines +86 to +89
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `api/vc-api.yaml` a master file with all specifications rolled into one
- `api/bundles/issuer.yml` issuer endpoints bundled with no external refs
- `api/bundles/verifier.yml` verifier endpoints bundled with no external refs
- `api/bundles/holder.yml` holder endpoints bundled with no external refs
- `api/vc-api.yaml` — a master file with all specifications rolled into one
- `api/bundles/issuer.yml` — issuer endpoints bundled with no external refs
- `api/bundles/verifier.yml` — verifier endpoints bundled with no external refs
- `api/bundles/holder.yml` — holder endpoints bundled with no external refs

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have the ability to accept this change (don't have access to @mprorock's repo). I will put this change in right after I merge.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implemented in 9b001e6.


## Additional Documentation

- [Verifiable Credential Issuer API Architecture Model](architecture.md)
Expand Down
16 changes: 16 additions & 0 deletions api/rapidoc.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!doctype html>
<html>

<head>
<title>VC-API</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 characters -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
</head>

<body>
<rapi-doc spec-url="./vc-api.yaml" theme="dark"> </rapi-doc>
</body>

</html>
27 changes: 27 additions & 0 deletions api/redoc.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<!DOCTYPE html>
<html>

<head>
<title>VC-API</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='./vc-api.yaml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
</body>

</html>
30 changes: 30 additions & 0 deletions api/swagger.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<html lang="en">

<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="SwaggerIU for VC-API" />
<title>VC-API</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
</head>

<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
url: './vc-api.yaml',
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
layout: "StandaloneLayout",
});
};
</script>
</body>

</html>
8 changes: 8 additions & 0 deletions holder.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ info:
paths:
/credentials/derive:
post:
tags:
- credential
summary: Derives a credential and returns it in the response body.
operationId: deriveCredential
description: Derives a credential and returns it in the response body.
Expand All @@ -37,6 +39,8 @@ paths:
/presentations/prove:
post:
summary: Proves a presentation and returns it in the response body.
tags:
- presentation
operationId: provePresentation
description: Proves a presentation and returns it in the response body.
requestBody:
Expand All @@ -59,6 +63,8 @@ paths:
/exchanges/{exchange-id}:
post:
summary: Initiates an exchange of information.
tags:
- exchange
operationId: initiateExchange
description:
A client can use this endpoint to initiate an exchange of a particular
Expand Down Expand Up @@ -103,6 +109,8 @@ paths:
/exchanges/{exchange-id}/{transaction-id}:
put:
summary: Receives information related to an existing exchange.
tags:
- exchange
operationId: receiveExchangeData
description:
A client can use this endpoint to continue the exchange of information
Expand Down
1 change: 1 addition & 0 deletions index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
// noop
4 changes: 4 additions & 0 deletions issuer.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ paths:
/credentials/issue:
post:
summary: Issues a credential and returns it in the response body.
tags:
- credential
operationId: issueCredential
description: Issues a credential and returns it in the response body.
requestBody:
Expand All @@ -35,6 +37,8 @@ paths:
/credentials/status:
post:
summary: Updates the status of an issued credential
tags:
- credential
operationId: updateCredentialStatus
description: Updates the status of an issued credential.
requestBody:
Expand Down
31 changes: 31 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"name": "vc-api",
"version": "0.0.3",
"description": "Verifiable Credential API",
"main": "index.js",
"scripts": {
"build": "openapi bundle *.yml --output ./api/bundles/ && openapi join ./api/bundles/*.yml --prefix-tags-with-filename && mv ./openapi.yaml ./api/vc-api.yaml"
},
"repository": {
"type": "git",
"url": "git+https://github.com/w3c-ccg/vc-api.git"
},
"keywords": [
"VC",
"DID",
"W3C"
],
"author": "public-credentials@w3.org",
"license": "Apache-2.0",
"bugs": {
"url": "https://github.com/w3c-ccg/vc-api/issues"
},
"homepage": "https://github.com/w3c-ccg/vc-api#readme",
"dependencies": {
"swagger-cli": "^4.0.4"
},
"devDependencies": {
"@redocly/openapi-cli": "^1.0.0-beta.87",
"redoc-cli": "^0.13.8"
}
}
4 changes: 4 additions & 0 deletions verifier.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ paths:
/credentials/verify:
post:
summary: Verifies a verifiableCredential and returns a verificationResult in the response body.
tags:
- credential
operationId: verifyCredential
description: Verifies a verifiableCredential and returns a verificationResult in the response body.
requestBody:
Expand All @@ -35,6 +37,8 @@ paths:
/presentations/verify:
post:
summary: Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body.
tags:
- presentation
operationId: verifyPresentation
description: Verifies a verifiablePresentation and returns a verificationResult in the response body. Given the possibility of denial of service, buffer overflow, or other style attacks, an implementation is permitted to rate limit or restrict requests against this API endpoint to those requests that contain only a single credential with a 413 or 429 error code as appropriate.
requestBody:
Expand Down