loopback-swagger

Utilities to transform between Swagger API specs and LoopBack remoting metadata.

This is an internal module used by the following user-facing tools:

• slc loopback:swagger
• loopback-component-explorer

---

Swagger-ui v3 with Security

This is a WIP fork of advanced swagger.json OAuth2 support for Loopback using latest swagger-ui (currently 3.9)

Key Repositories

• drmikecrowe: loopback-component-explorer
• drmikecrowe: loopback-swagger

SwaggerUI v3 Support Status

• Integrate v3 of the SwaggerUI (using swagger-ui-dist)
• securityDefinitions Support
• Integrate with loopback-component-explorer.
  • Update explorer to use new Swagger-UI
  • Test and document using oauth2-redirect for OAuth2 local development
• Tested Grant Types
  • implicit
  • jwt
  • clientCredentials
  • authorizationCode
  • refreshToken
  • resourceOwnerPasswordCredentials
• Review @raymongfeng realm discussions and determine insure this strategy meets Strongloop plans
• Update automated tests
• Review loopback style guide

Installation

• See drmikecrowe: loopback-component-explorer README for current installation instructions

Development redirectURIs

For development only, you may add the following redirectURI to your applications object (assuming your API is running on localhost:3001, and your authentication server is running on localhost:3000):

"redirectURIs" : [
"http://localhost:3001/explorer/oauth2-redirect.html"
], 

Add detailed API info to your component-config

In your component-config.local.js, OAuth2 configuration may be specified as follows:

varpath=require('path');module.exports={"loopback-component-explorer": {"mountPath": "/explorer","uiDirs": "explorer","apiInfo": {"title": "Loopback API Explorer","description": "A description of my API","version": require('../package.json').version,"termsOfService": "http://my-super-site.com/terms","contact": {"name": "Support Team","email": "support@my-super-site.com"}},"host": "my-super-site.com","schemes": ["http","https"],"consumes": ["application/json"],"produces": ["application/json","application/xml"],"securityDefinitions": {"OauthPassword": {"type": "oauth2","flow": "implicit","description": "OAuth2 Password authentication","authorizationUrl": path.join("/oauth/authorize"),"scopes": {"read": "Access API methods","write": "Update API methods"}},"OauthAccessCode": {"type": "oauth2","description": "OAuth2 Access Code authentication","flow": "accessCode","authorizationUrl": path.join("/oauth/authorize"),"tokenUrl": path.join("/oauth/token"),"scopes": {"read": "Access API methods","write": "Update API methods"}}},"security": [{"OauthAccessCode": ["read","write"],"OauthPassword": ["read","write"]}]}};

I implemented via component-config.local.js in order to allow the path module in case the authorization server were needed to be a separate URL.

This produces swagger.yaml such as the following:

info:
title: Loopback API Explorerdescription: A description of my APIversion: 0.1.26contact:
email: support@my-super-site.comname: Support TeamtermsOfService: 'http://my-super-site.com/terms'basePath: /api/v1host: my-super-site.comconsumes:
- application/jsonproduces:
- application/json
- application/xmlsecurityDefinitions:
OauthPassword:
type: oauth2flow: implicitdescription: OAuth2 Password authenticationauthorizationUrl: /oauth/authorizescopes:
read: Access API methodswrite: Update API methodsOauthAccessCode:
type: oauth2description: OAuth2 Access Code authenticationflow: accessCodeauthorizationUrl: /oauth/authorizetokenUrl: /oauth/tokenscopes:
read: Access API methodswrite: Update API methodssecurity:
- OauthAccessCode:
- read
- writeOauthPassword:
- read
- writepaths: {}definitions: {}tags: {}

Route Specific Scopes

IF you need to specify a specific OAuth2 Scope at a Loopback method level, this project supports that functionality in a limited fashion:

• The swagger.json will syntatically be correct per the JSON schema definition for Swagger v2.
• It does NOT implement a custom role-resolver for that specific method. That will be left to each application.

To specify a specific scope on a single route, in the model definition file:

{
"acls": [
{
"accessType": "EXECUTE",
"principalType": "OauthPassword",
"principalId": "createSomething",
"scope": "write",
"permission": "ALLOW"
}
]
}

will produce Swagger yaml such as:

'/MyModel/createSomething':
post:
tags:
- MyModeloperationId: MyModel.createSomethingparameters:
- name: datain: bodydescription: >- Data object to be savedrequired: trueschema:
description: >- Data object to be saved$ref: '#/definitions/SomethingObject'responses:
'200':
description: Request was successfulschema:
$ref: '#/definitions/Something'deprecated: falsesecurity:
- OauthPassword:
- write