Skip to content

Commit

Permalink
Merge pull request swagger-api#983 from swagger-api/migration-guide
Browse files Browse the repository at this point in the history 
README update and addition of docs/
  • Loading branch information
@ponelat
ponelat authored Mar 29, 2017
2 parents 92e0adb + a96b9c1 commit 9035699
Show file tree
Hide file tree
Showing 5 changed files with 509 additions and 63 deletions.
152 changes: 90 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,21 @@ Swagger-JS

For the older version of swagger-js, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-js/tree/2.x).


## Note:
The npm package is called `swagger-client` and the GitHub repository is `swagger-js`.
We'll be consolidating that soon. Just giving you the heads up. You may see references to both names.

### Usage

##### Prerequisites
- Node 4.x
- NPM 2.x
- Runtime:
- browser: es5 compatible. IE11+
- node v4.x.x
- Building
- node v6.x.x

##### Download via NPM
##### Download via npm

```
npm install swagger-client
Expand All @@ -25,25 +33,31 @@ npm install swagger-client

```javascript
import Swagger from 'swagger-client'
// Or commonjs
const Swagger = require('swagger-client')
```

#### API

This lib exposes these functionalities:

1. HTTP Client
1. Swagger Spec Resolver
1. TryItOut Executor
1. Tags Interface
1. JS API
- Static functions for...
- HTTP Client
- Swagger Spec Resolver ( OAS 2.0 )
- TryItOut Executor
- A constructor with the methods...
- HTTP Client, for convenience
- Swagger Spec Resolver ( OAS 2.0 ), which will use `url` or `spec` from the instance
- TryItOut Executor, bound to the `http` and `spec` instance properties
- Tags Interface, also bound to the instance

HTTP Client
-----------

`Swagger.http(req)` exposes a [Fetch-like interface](https://github.com/matthew-andrews/isomorphic-fetch) with a tweak: allowing `url` in the request object so that it can be passed around and mutated. It extends Fetch to support request and response interceptor and perform response & headers serialization. This method could be overridden to change how SwaggerJS performs HTTP requests.
`Swagger.http(req)` exposes a [Fetch-like interface](https://github.com/matthew-andrews/isomorphic-fetch) with a twist: allowing `url` in the request object so that it can be passed around and mutated. It extends Fetch to support request and response interceptors and performs response & header serialization. This method could be overridden to change how SwaggerJS performs HTTP requests.

```js
// Fetch-like, but support `url`
// Fetch-like, but support `url`, `query` and `xxxInterceptor`
const request = {
url,
query,
Expand All @@ -57,10 +71,10 @@ const request = {
Swagger.http(request)
.then((res) => {
res.statusCode // status code
res.statusText // status text
res.statusText // status text, ie: "Not Found"
res.body // JSON object or undefined
res.obj // same as above, legacy
res.text // textual body
res.text // textual body, or Blob
res.headers // header hash
})
.catch((err) => {
Expand All @@ -76,7 +90,7 @@ Swagger.http({

```

Swagger Spec Resolver
Swagger Specification Resolver
---------------------

`Swagger.resolve({url, spec, http})` resolves `$ref`s (JSON-Refs) with the objects they point to.
Expand All @@ -88,32 +102,65 @@ Swagger.resolve({url, spec, http}).then((resolved) => {
resolved.spec // the resolved spec
})
```
> This is done automatically if you use the constructor/methods
TryItOut Executor
-----------------
An HTTP client for OAI operations, maps an operation and values into a request/response.
An HTTP client for OAS operations, maps an operation and values into an HTTP request.

```js
const params = {
spec,
operationId,

operationId, // Either operationId, or you can use pathName + method
(pathName),
(method),
parameters,
securities,
requestContentType,
responseContentType

parameters, // _named_ parameters in an object, eg: { petId: 'abc' }
securities, // _named_ securities, will only be added to the request, if the spec indicates it. eg: {apiKey: 'abc'}
requestContentType,
responseContentType,

(http), // You can also override the HTTP client completely
}

// Creates a request object compatible with HTTP client interface.
// If `pathName` and `method`, then those are used instead of operationId.
const req = Swagger.buildRequest(...params)
Swagger.execute({http, ...params})
// If `pathName` and `method`, then those are used instead of operationId. This is useful if you're using this dynamically, as `pathName` + `method` are guarenteed to be unique.
const res = Swagger.execute({...params})

// You can also generate just the request ( without executing... )
const req = Swagger.buildRequest({...params})
```

Constructor and methods
-----------------------

Resolve the spec and expose some methods that use the resolved spec:

- `Swagger(url, opts): Promise`
- Exposes tags interface (see above)
- Exposes the static functions: `execute`, `http`, `resolve` and some other minor ones
- Exposes `#http`, `#execute` and `#resolve` bound to the instance

```javascript
Swagger('http://petstore.swagger.io/v2/swagger.json')
.then( client => {
client.spec // The resolved spec
client.originalSpec // In case you need it
client.errors // Any resolver errors

// Tags interface
client.apis.pet.addPet({id: 1, name: "bobby"}).then(...)

// TryItOut Executor, with the `spec` already provided
client.execute({operationId: 'addPet', parameters: {id: 1, name: "bobby") }).then(...)
})

```
Tags Interface
--------------
A JS client for operations. We're currently using the `apis[tag][operationId]:ExecuteFunction` interface, which can be disabled entirely using `Swagger({disableInterfaces: true})` if you don't need it.
A client for operations. We're currently using the `apis[tag][operationId]:ExecuteFunction` interface, which can be disabled entirely using `Swagger({disableInterfaces: true})` if you don't need it.
OperationId's are meant to be unique within spec, if they're not we do the following:
- If a tag is absent, we use `default` as the internal tag
Expand All @@ -122,20 +169,14 @@ OperationId's are meant to be unique within spec, if they're not we do the follo
```js
Swagger({...}).then((client) => {
client.apis.pets.addPet({id: 1, name: "bobby"}).then(...)
client
.apis
.pet // tag name == `pet`
.addPet({id: 1, name: "bobby"}) // operationId == `addPet`
.then(...)
})
```
JS API
------

Resolve the spec and expose some methods that use the resolved spec:

- `Swagger(url, opts): Promise`
- Exposes tags interface (see above)
- Exposes the static functions: `execute`, `http`, `resolve` and some other minor ones
- Exposes `#http`, `#execute` and `#resolve` bound to the instance

Compatibility
-------------
Expand All @@ -151,8 +192,9 @@ SwaggerJS has some legacy signature _shapes_.
status,
statusText,
headers,
data,
obj

data, // The textual content
obj // The body object
}

// New shape
Expand All @@ -162,8 +204,9 @@ SwaggerJS has some legacy signature _shapes_.
status,
statusText,
headers, // See note below regarding headers

text, // The textual content
body, // a JSON object
body, // The body object
}
```
Expand All @@ -173,31 +216,6 @@ By default the instance version of `#http` serializes the body and headers.
However, headers pose an issue when there are multiple headers with the same name.
As such we've left the static version of `http` to not perform any serialization.
##### Interfaces

```js
// Interface #1
// Pro: code readability
// Con: conflicts with SwaggerJS named properties, which means we need to rename tags or properties (both aren't fun).
client[tag][operation]:ExecuteFunction

// Interface #2
// Pro: No conflicts, the whole api is under `apis` property
// Con: an unusual use of the named `operation` and `execute` properties, instead of simply making the operation the function
client.apis[tag].operation.[operation].execute:ExecuteFunction

// Interface #3
// Pro: No conflicts with SwaggerJS property names
// Con: Not directly bound to the interface, ie: its under `apis`
client.apis[tag][operation]:ExecuteFunction

// Interface #4
// Pro: direct access to operationIds
// Con: No tags
client.ops[operation]:ExecuteFunction
```


### Build
```sh
Expand All @@ -207,3 +225,13 @@ npm run test:watch # run test with change watching
npm run lint # run lint
npm run build # package to release
```
# Migration from 2.x
There has been a complete overhaul of the codebase.
For notes about how to migrate coming from 2.x,
please see [Migration from 2.x](docs/MIGRATION_2_X.md)
### Graveyard
For features known to be missing from 3.x please see [the Graveyard](docs/GRAVEYARD.md)
65 changes: 65 additions & 0 deletions docs/GRAVEYARD.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
Graveyard
---------

### features no longer supported

During the course of the refactor some items were left behind.
Some of these may be resuscitated as needed.
But for the most part we can consider them excluded.

- client.apisArray
- client.apisArray[i].operationsArray
- client.modelsArray
- client.authorizationScheme
- client.basePath
- client.build
- client.buildFrom1_1Spec
- client.buildFrom1_2Spec
- client.buildFromSpec
- client.clientAuthorizations
- client.convertInfo
- client.debug
- client.defaultErrorCallback
- client.defaultSuccessCallback
- client.enableCookies
- client.fail
- client.failure
- client.finish
- client.help
- client.host
- client.idFromOp
- client.info
- client.initialize
- client.isBuilt
- client.isValid
- client.modelPropertyMacro
- client.models
- client.modelsArray
- client.options
- client.parameterMacro
- client.parseUri
- client.progress
- client.resourceCount
- client.sampleModels
- client.selfReflect
- client.setConsolidatedModels
- client.supportedSubmitMethods
- client.swaggerRequestHeaders
- client.tagFromLabel
- client.title
- client.useJQuery
- client.jqueryAjaxCach

- client.apis[tag]
- .apis
- .asCurl
- .description
- .externalDocs
- .help
- .label
- .name
- .operation
- .operations
- .operationsArray
- .path
- .tag
Loading

0 comments on commit 9035699

Please sign in to comment.