{"id":19874465,"url":"https://github.com/strongloop/loopback-connector-swagger","last_synced_at":"2025-07-07T08:09:26.551Z","repository":{"id":66071272,"uuid":"55775930","full_name":"strongloop/loopback-connector-swagger","owner":"strongloop","description":"Connect Loopback to a Swagger-compliant API","archived":false,"fork":false,"pushed_at":"2019-07-25T15:19:08.000Z","size":107,"stargazers_count":19,"open_issues_count":0,"forks_count":13,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-07-07T08:04:54.724Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strongloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-08T12:03:18.000Z","updated_at":"2022-06-08T15:34:25.000Z","dependencies_parsed_at":"2023-02-20T19:30:56.542Z","dependency_job_id":null,"html_url":"https://github.com/strongloop/loopback-connector-swagger","commit_stats":{"total_commits":34,"total_committers":15,"mean_commits":"2.2666666666666666","dds":0.7058823529411764,"last_synced_commit":"f6c9b0aa5d796df2343fc876b9854a0952b9e458"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/strongloop/loopback-connector-swagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Floopback-connector-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Floopback-connector-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Floopback-connector-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Floopback-connector-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strongloop","download_url":"https://codeload.github.com/strongloop/loopback-connector-swagger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Floopback-connector-swagger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264040939,"owners_count":23548070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T16:23:27.944Z","updated_at":"2025-07-07T08:09:26.502Z","avatar_url":"https://github.com/strongloop.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"**This repository is now deprecated. Please use https://github.com/strongloop/loopback-connector-openapi instead.**\n\n# loopback-connector-swagger\nThe Swagger connector enables LoopBack applications to interact with other REST APIs described by the [OpenAPI (Swagger) Specification v.2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).\n\n## Installation\n\nIn your application root directory, enter:\n```\n$ npm install loopback-connector-swagger --save\n```\n\nThis will install the module from npm and add it as a dependency to the application's `package.json` file.\n\n## Configuration\n\nTo interact with a Swagger API, configure a data source backed by the Swagger connector:\n\nWith code:\n\n```javascript\n  var ds = loopback.createDataSource('swagger', {\n    connector: 'loopback-connector-swagger',\n    spec: 'http://petstore.swagger.io/v2/swagger.json',\n  });\n```\n\nWith JSON in `datasources.json` (for example, with basic authentication):\n\n```\n\"SwaggerDS\": {\n    \"name\": \"SwaggerDS\",\n    \"connector\": \"swagger\",\n    \"spec\": \"http://petstore.swagger.io/v2/swagger.json\",\n    \"security\": {\n      \"type\" : \"basic\",\n      \"username\": \"the user name\",\n      \"password\": \"thepassword\"\n}\n```\n\n### Caching\n\nAs an experimental feature, loopback-connector-swagger is able to cache the result of `GET` requests.\n\n**Important: we support only one cache invalidation mechanism - expiration based on a static TTL value.**\n\nTo enable caching, you need to specify:\n\n - `cache.model` (required) - name of the model providing access to the cache.\n   The model should be extending loopback's built-in `KeyValueModel`\n   and be attached to one of key-value datasources (e.g. Redis or\n   eXtremeScale).\n\n - `cache.ttl` (required) - time to live for cache entries, the value\n   is in milliseconds. Note that certain cache implementations (notably\n   eXtremeScale) do not support sub-second precision for TTL.\n\n#### Example configuration\n\n`server/datasources.json`\n\n```json\n{\n  \"SwaggerDS\": {\n    \"connector\": \"swagger\",\n    \"cache\": {\n      \"model\": \"SwaggerCache\",\n      \"ttl\": 100\n    }\n  },\n  \"cache\": {\n    \"connector\": \"kv-redis\",\n  }\n}\n```\n\n`common/models/swagger-cache.json`\n\n```\n{\n  \"name\": \"SwaggerCache\",\n  \"base\": \"KeyValueModel\",\n  // etc.\n}\n```\n\n`server/model-config.json`\n```\n{\n  \"SwaggerCache\": {\n    \"dataSource\": \"cache\",\n    \"public\": false\n  }\n}\n```\n\n## Data source properties\n\nSpecify the options for the data source with the following properties.\n\n| Property | Description | Default   |\n|----------|-------------|-----------|\n| connector | Must be `'loopback-connector-swagger'` to specify Swagger connector| None |\n|spec      | HTTP URL or path to the Swagger specification file (with file name extension `.yaml/.yml` or `.json`).  File path must be relative to current working directory (`process.cwd()`).| None |\n|validate | When `true`, validates provided `spec` against Swagger specification 2.0 before initializing a data source. | `false`|\n| security | Security configuration for making authenticated requests to the API.  The `security.type` property specifies authentication type, one of: Basic authentication (`basic`), API Key (`apiKey`), or OAuth2 (`oauth2`). | `basic` |\n\n### Authentication\n\nBasic authentication:\n\n```javascript\nsecurity: {\n  type: 'basic', // default type, not to be changed\n  username: 'the user name',\n  password: 'password'\n}\n```\n\nAPI Key:\n\n```javascript\nsecurity: {\n  type: 'apiKey', // default type, not to be changed\n  name: 'api_key',\n  key: 'yourAPIKey',\n  in: 'query' // or 'header'\n}\n```\n\nOAuth2:\n\n```javascript\nsecurity:{\n  type: 'oauth2', // default type, not to be changed\n  name: 'oauth_scheme',\n  accessToken: 'sampleAccessToken', // access token\n  in: 'query' // defaults to `header` if not set\n}\n```\n\n**Note**: The value of the `name` property must correspond to a security scheme declared in the [Security Definitions object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object) within the `spec` document.\n\n### Creating a model from the Swagger data source\n\nThe Swagger connector loads the API specification document asynchronously. As a result, the data source won't be ready to create models until it is connected.  For best results, use an event handler for the `connected` event of data source:\n\n```javascript\nds.once('connected', function(){\n  var PetService = ds.createModel('PetService', {});\n  ...\n});\n```\nOnce the model is created, all available Swagger API operations can be accessed as model methods, for example:\n\n```javascript\n...\nPetService.getPetById({petId: 1}, function (err, res){\n  ...\n});\n```\n\n#### How model methods are named for given Swagger API Operations:\nThis connector uses [swagger-client](https://github.com/swagger-api/swagger-js) which dominates the naming of generated methods for calling client API operations.\n\nFollowing is how it works:\n\n- When `operationId` is present, for example:\n\n```javascript\npaths: {\n  /weather/forecast:\n  get:\n    ...\n    operationId: weather.forecast\n    ...\n```\n  Here, as `operationId` is present in Swagger specification, the generated method is named equivalent to `operationId`.\n\n  Note:\n      if `operationId` is of format equivalent to calling a nested function such as: `weather.forecast`, the resulting method name will replace `.` with `_` i.e. `weather.forecast` will result into `weather_forecast`.This means you can call `MyModel.weather_forecast()` to access this endpoint programmatically.\n\n- When `operationId` is not provided in Swagger specification, the method name is formatted as following:\n`\u003coperationType (i.e. get, post, etc)\u003e + _ + \u003cpath parts separated by underscores\u003e`\n\nFor example:\n```\n/weather/forecast:\n  get:\n    ...\n```\nfor above operation, the resulting method name will be: `get_weather_forecast`.\n\nThis means you can call `MyModel.get_weather_forecast()` to access this endpoint programmatically.\n\n### Extend a model to wrap/mediate API Operations\nOnce you define the model, you can wrap or mediate it to define new methods. The following example simplifies the `getPetById` operation to a method that takes `petID` and returns a Pet instance.\n\n```javascript\n  PetService.searchPet = function(petID, cb){\n    PetService.getPetById({petId: petID}, function(err, res){\n      if(err) cb(err, null);\n      var result = res.data;\n      cb(null, result);\n    });\n  };\n```\n\nThis custom method on the `PetService` model can be exposed as REST API end-point. It uses `loopback.remoteMethod` to define the mappings:\n\n```javascript\nloopback.remoteMethod(\n  PetService.searchPet, {\n    accepts: [\n      { arg: 'petID', type: 'string', required: true,\n        http: { source: 'query' }\n      }\n    ],\n    returns: {arg: 'result', type: 'object', root: true },\n    http: {verb: 'get', path: '/searchPet'}\n  }\n);\n```\n\n### Example\n\nComing soon...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Floopback-connector-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrongloop%2Floopback-connector-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Floopback-connector-swagger/lists"}