Skip to content

[prototype]Upgrade Swagger 2 to OpenAPI 3 #916

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

Closed
jannyHou wants to merge 1 commit into from
Closed

[prototype]Upgrade Swagger 2 to OpenAPI 3 #916

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion packages/authentication/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
"dependencies": {
"@loopback/context": "^4.0.0-alpha.31",
"@loopback/core": "^4.0.0-alpha.33",
"@loopback/openapi-v2": "^4.0.0-alpha.10",
"@loopback/openapi-v3": "^4.0.0-alpha.1",
"@loopback/rest": "^4.0.0-alpha.25",
"passport": "^0.4.0",
"passport-strategy": "^1.0.0"
Expand Down
2 changes: 1 addition & 1 deletion packages/authentication/test/acceptance/basic-auth.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ import {
RestServer,
RestComponent,
} from '@loopback/rest';
import {api, get} from '@loopback/openapi-v2';
import {api, get} from '@loopback/openapi-v3';
import {Client, createClientForHandler} from '@loopback/testlab';
import {anOpenApiSpec} from '@loopback/openapi-spec-builder';
import {inject, Provider, ValueOrPromise} from '@loopback/context';
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/generators/app/templates/src/controllers/ping.controller.ts.template
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {ServerRequest} from '@loopback/rest';
import {get} from '@loopback/openapi-v2';
import {get} from '@loopback/openapi-v3';
import {inject} from '@loopback/context';

/**
Expand Down
2 changes: 1 addition & 1 deletion .../cli/generators/controller/templates/src/controllers/controller-rest-template.ts.template
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {Filter, Where} from '@loopback/repository';
import {post, param, get, put, patch, del} from '@loopback/openapi-v2';
import {post, param, get, put, patch, del} from '@loopback/openapi-v3';
import {inject} from '@loopback/context';
import {<%= modelName %>} from '../models';
import {<%= repositoryName %>} from '../repositories';
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/generators/project/templates/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@
<% if (project.projectType === 'application') { -%>
"@loopback/core": ">=4.0.0-alpha.20",
"@loopback/rest": ">=4.0.0-alpha.7",
"@loopback/openapi-v2": ">=4.0.0-alpha.2"
"@loopback/openapi-v3": ">=4.0.0-alpha.1"
<% } else { -%>
"@loopback/core": ">=4.0.0-alpha.20"
<% } -%>
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/generators/project/templates/package.plain.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@
<% if (project.projectType === 'application') { -%>
"@loopback/core": ">=4.0.0-alpha.20",
"@loopback/rest": ">=4.0.0-alpha.7",
"@loopback/openapi-v2": ">=4.0.0-alpha.2"
"@loopback/openapi-v3": ">=4.0.0-alpha.1"
<% } else { -%>
"@loopback/core": ">=4.0.0-alpha.20"
<% } -%>
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/test/app.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ describe('app-generator specfic files', () => {
assert.fileContent('src/controllers/ping.controller.ts', /ping\(\)/);
assert.fileContent(
'src/controllers/ping.controller.ts',
/\'\@loopback\/openapi\-v2\'/
/\'\@loopback\/openapi\-v3\'/
);

assert.file;
Expand Down
4 changes: 2 additions & 2 deletions packages/cli/test/project.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ module.exports = function(projGenerator, props, projectType) {
assert.fileContent('package.json', '"@loopback/core"');
assert.fileContent('package.json', '"@loopback/context"');
assert.fileContent('package.json', '"@loopback/rest"');
assert.fileContent('package.json', '"@loopback/openapi-v2"');
assert.fileContent('package.json', '"@loopback/openapi-v3"');
assert.jsonFileContent('package.json', {
scripts: {
start: 'npm run build && node .',
Expand All @@ -222,7 +222,7 @@ module.exports = function(projGenerator, props, projectType) {
assert.fileContent('package.json', '"@loopback/core"');
assert.fileContent('package.json', '"@loopback/context"');
assert.noFileContent('package.json', '"@loopback/rest"');
assert.noFileContent('package.json', '"@loopback/openapi-v2"');
assert.noFileContent('package.json', '"@loopback/openapi-v3"');
assert.noJsonFileContent('package.json', {
start: 'npm run build && node .',
});
Expand Down
2 changes: 1 addition & 1 deletion packages/example-getting-started/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
"@loopback/context": "^4.0.0-alpha.31",
"@loopback/core": "^4.0.0-alpha.33",
"@loopback/openapi-spec": "^4.0.0-alpha.25",
"@loopback/openapi-v2": "^4.0.0-alpha.10",
"@loopback/openapi-v3": "^4.0.0-alpha.1",
"@loopback/repository": "^4.0.0-alpha.29",
"@loopback/rest": "^4.0.0-alpha.25"
},
Expand Down
21 changes: 15 additions & 6 deletions packages/example-getting-started/src/controllers/todo.controller.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
import {post, param, get, put, patch, del} from '@loopback/openapi-v2';
import {
post,
param,
get,
put,
patch,
del,
requestBody,
} from '@loopback/openapi-v3';
import {HttpErrors} from '@loopback/rest';
import {TodoSchema, Todo} from '../models';
import {repository} from '@loopback/repository';
Expand All @@ -13,7 +21,10 @@ export class TodoController {
) {}
@post('/todo')
async createTodo(
@param.body('todo', TodoSchema)
// TODO(janny) The requestBody Spec will be empty after we
// 1. update to generate schema from bottom-up
// 2. decide the default content type
@requestBody({content: {'application/json': {schema: TodoSchema}}})
todo: Todo,
) {
// TODO(bajtos) This should be handled by the framework
Expand All @@ -40,30 +51,28 @@ export class TodoController {
@put('/todo/{id}')
async replaceTodo(
@param.path.number('id') id: number,
@param.body('todo', TodoSchema)
@requestBody({content: {'application/json': {schema: TodoSchema}}})
todo: Todo,
): Promise<boolean> {
// REST adapter does not coerce parameter values coming from string sources
// like path & query. As a workaround, we have to cast the value to a number
// ourselves.
// See https://github.com/strongloop/loopback-next/issues/750
id = +id;

return await this.todoRepo.replaceById(id, todo);
}

@patch('/todo/{id}')
async updateTodo(
@param.path.number('id') id: number,
@param.body('todo', TodoSchema)
@requestBody({content: {'application/json': {schema: TodoSchema}}})
todo: Todo,
): Promise<boolean> {
// REST adapter does not coerce parameter values coming from string sources
// like path & query. As a workaround, we have to cast the value to a number
// ourselves.
// See https://github.com/strongloop/loopback-next/issues/750
id = +id;

return await this.todoRepo.updateById(id, todo);
}

Expand Down
2 changes: 1 addition & 1 deletion packages/example-getting-started/src/models/todo.model.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {Entity, property, model} from '@loopback/repository';
import {SchemaObject} from '@loopback/openapi-spec';
import {SchemaObject} from '@loopback/openapi-spec-types';

@model()
export class Todo extends Entity {
Expand Down
2 changes: 1 addition & 1 deletion packages/openapi-spec-builder/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
"Testing"
],
"dependencies": {
"@loopback/openapi-spec": "^4.0.0-alpha.25"
"@loopback/openapi-spec-types": "^4.0.0-alpha.1"
},
"devDependencies": {
"@loopback/build": "^4.0.0-alpha.13"
Expand Down
16 changes: 14 additions & 2 deletions packages/openapi-spec-builder/src/openapi-spec-builder.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ import {
ResponseObject,
ParameterObject,
createEmptyApiSpec,
} from '@loopback/openapi-spec';
RequestBodyObject,
} from '@loopback/openapi-spec-types';

/**
* Create a new instance of OpenApiSpecBuilder.
Expand Down Expand Up @@ -137,7 +138,13 @@ export class OperationSpecBuilder extends BuilderBase<OperationObject> {
withStringResponse(status: number | 'default' = 200): this {
return this.withResponse(status, {
description: 'The string result.',
schema: {type: 'string'},
content: {
// TODO(janny) will change it to a default value
// after we figure out the plan for content type
'*/*': {
schema: {type: 'string'},
},
},
});
}

Expand All @@ -154,6 +161,11 @@ export class OperationSpecBuilder extends BuilderBase<OperationObject> {
return this;
}

withRequestBody(requestBodySpec: RequestBodyObject): this {
this._spec.requestBody = requestBodySpec;
return this;
}

/**
* Define the operation name (controller method name).
*
Expand Down
3 changes: 3 additions & 0 deletions packages/openapi-spec-types/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
*.tgz
dist*
package
0 packages/openapi-spec/.npmrc → packages/openapi-spec-types/.npmrc
View file
Open in desktop
File renamed without changes.
0 packages/openapi-spec/CHANGELOG.md → packages/openapi-spec-types/CHANGELOG.md
View file
Open in desktop
File renamed without changes.
0 packages/openapi-spec/LICENSE → packages/openapi-spec-types/LICENSE
View file
Open in desktop
File renamed without changes.
30 changes: 26 additions & 4 deletions packages/openapi-spec/README.md → packages/openapi-spec-types/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,20 @@ TypeScript type definitions for OpenAPI Spec/Swagger documents.
TypeScript definitions describing the schema of OpenAPI/Swagger documents,
including LoopBack-specific extensions.

_@jannyHou: will add more doc here to specify the version of types after we decide how to support new versions/keep old versions_

## Installation

```
$ npm install --save @loopback/openapi-spec
$ npm install --save @loopback/openapi-spec-types
```

## Basic use

Use `OpenApiSpec` type in your function accepting a Swagger/OpenAPI document:
Use `OpenApiSpec` type in your function accepting an OpenAPI document:

```ts
import {OpenApiSpec} from '@loopback/openapi-spec';
import {OpenApiSpec} from '@loopback/openapi-spec-types';

export function validateSpec(spec: OpenApiSpec) {
// ...
Expand All @@ -30,7 +32,7 @@ when constructing a spec argument value.

## Related resources

See https://www.openapis.org/ and [version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
See https://www.openapis.org/ and [version 3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
of OpenAPI Specification.

## Contributions
Expand All @@ -48,3 +50,23 @@ See [all contributors](https://github.com/strongloop/loopback-next/graphs/contri
# License

MIT

# Question

Do we want multiple repos for types?

option 1
- openapi-spec-types
- swagger-spec-types

option 2
- openapi-spec-types
- /v2
- /v3


Benefit of single repo:

* easy to extract common suger interfaces
* less packages to maintain, clear layout to manage different versions
* if we only support one version, export types from one package, no need to update each dependant
Copy link
Member

@bajtos bajtos Feb 15, 2018

Choose a reason for hiding this comment

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

I believe we have already agreed to support only a single version of OpenAPI spec?

IMO, we should have a single repo describing only the current (latest) version of OpenAPI spec.

When a new, backwards-incompatible version of OAI is released, then we will release a new semver-major version of this package.

Copy link
Member

@bajtos bajtos Feb 15, 2018

Choose a reason for hiding this comment

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

IMO, we should have a single repo describing only the current (latest) version of OpenAPI spec.

When a new, backwards-incompatible version of OAI is released, then we will release a new semver-major version of this package.

Let me take that back. Considering the effort needed to upgrade between OAI versions, I think it's better to have a new package for each major revision of OAI spec, because it makes it easier for us to split the work into independent chunks.

0 packages/openapi-spec/docs.json → packages/openapi-spec-types/docs.json
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion packages/openapi-spec/index.d.ts → packages/openapi-spec-types/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Copyright IBM Corp. 2017,2018. All Rights Reserved.
// Node module: @loopback/openapi-spec
// Node module: @loopback/openapi-spec-types
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

Expand Down
2 changes: 1 addition & 1 deletion packages/openapi-spec/index.js → packages/openapi-spec-types/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Copyright IBM Corp. 2017,2018. All Rights Reserved.
// Node module: @loopback/openapi-spec
// Node module: @loopback/openapi-spec-types
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

Expand Down
2 changes: 1 addition & 1 deletion packages/openapi-spec/index.ts → packages/openapi-spec-types/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Copyright IBM Corp. 2017,2018. All Rights Reserved.
// Node module: @loopback/openapi-spec
// Node module: @loopback/openapi-spec-types
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT

Expand Down
Loading