OpenAPI Extensions¶
Every Composer project starts with an OpenAPI specification file. OpenAPI is a standard, language-agnostic, document format for describing RESTful APIs. It is from this document that both server and client code can be easily generated using the CLI tool. This enables developers to save time on initial project creation as well as providing consistent and well-documented APIs for others to use long after the project is deployed.
The OpenAPI specification is somewhat limited, however, and avoids describing certain details about the implementation of a RESTful API. Details that a code generator and framework like Composer must have in order to do its job properly. Therefore, we have extended the specification to add several new features.
Datastore Objects¶
Holds a set of datastore connection configurations. All objects defined within the x-datastores
object are copied
to the service’s config.ts
file. Schema objects desiring to be bound to a given Datastore Object must explicitly
reference it using the x-datastore
field.
Example
1 components:
2 x-datastores:
3 mongodb:
4 type: mongodb
5 url: mongodb://localhost
Datastore Object¶
Holds the name and associated configuration for a particular datastore connection. All properties defined in the object
are copied to the service’s config.ts
file. Configuration options should conform to the
TypeORM Connection Options. Desired Schema objects that are to be bound
to a given Datastore object must be explicitly referenced with the x-datastore
field where the value matches
the name of the object.
Example
1 components:
2 x-datastores:
3 mongodb:
4 type: mongodb
5 url: mongodb://localhost
Schema Object¶
The following extensions apply to Schema definitions.
x-baseClass
¶
Default Value: null
The x-baseClass
field is applied to a Schema
to identify the base class behavior that the generated Schema class will inherit. There are three possible values
presently supported by Composer.
Possible Values:
BaseMongoEntity
- Provides base behavior for all Schema classes that will be stored in a collection of a MongoDB database.BaseSQLEntity
- Provides base behavior for all Schema classes that will be stored in a SQL database.
Example
1 components:
2 schemas:
3 Order:
4 type: "object"
5 x-baseClass: BaseMongoEntity
6 x-datastore: mongodb
x-datastore
¶
Default Value: null
The x-datastore
field is applied to a Schema to identify
which database connection the schema will be bound to. The name of the database connection must match a defined
Datastore Object.
Example
1 components:
2 schemas:
3 Order:
4 type: "object"
5 x-baseClass: BaseMongoEntity
6 x-datastore: mongodb
x-ignore
¶
Default Value: false
The x-ignore
field is applied to a Schema Property to
indicate that it should be ignored from code generation.
Example
1 components:
2 schemas:
3 Order:
4 type: "object"
5 x-ignore: true
Schema Properties¶
The following extensions have been added to Schema Object Property definitions.
x-identifier
¶
Default Value: false
The x-identifier
field is applied to a Schema Property to
indicate that the field is a unique identifier within the database and should be indexed and must be unique.
Example
1 components:
2 schemas:
3 Order:
4 type: "object"
5 x-baseClass: BaseMongoEntity
6 x-datastore: mongodb
7 properties:
8 name:
9 type: "string"
10 x-identifier: true
11 x-unique: true
12 nullable: false
x-unique
¶
Default Value: false
The x-unique
field is applied to a Schema Property to
indicate that the field is a unique identifier within the database and must be unique.
Example
1 components:
2 schemas:
3 Order:
4 type: "object"
5 x-baseClass: BaseMongoEntity
6 x-datastore: mongodb
7 properties:
8 name:
9 type: "string"
10 x-identifier: true
11 x-unique: true
12 nullable: false
Path Item Object¶
The following extensions apply to Path Item Object definitions.
x-name
¶
Default Value: null
The x-name
field is applied to a Path Item Object. It
defines the unique name of the path item and the name of the generated code route handler class. This field is
superseded by the x-schema
field.
Example
1 paths:
2 /user/login:
3 x-name: Auth
4 get:
5 description: Authenticates the user using HTTP Basic and returns a JSON Web Token access token to be used with future API requests.
6 x-name: login
7 responses:
8 "200":
9 description: The JSON Web Token to be used for all future requests.
10 content:
11 application/json:
12 schema:
13 $ref: "#/components/schemas/authToken"
Generated Code
1/**
2 * Handles all REST API requests for the endpoint `/user/login`.
3 *
4 * @author <AUTHOR>
5 */
6@Route("/user/login")
7class AuthRoute {
8 @Config
9 protected config: any;
10 @Logger
11 protected logger: any;
12
13 /**
14 * Initializes a new instance with the specified defaults.
15 */
16 constructor() {
17 }
18 ...
19}
x-schema
¶
Default Value: null
The x-schema
field is applied to a Path Item Object. It
defines the Schema that the path item is bound to. This supersedes the x-name
field.
Example
1 paths:
2 /pet:
3 x-schema: Pet
4 get:
5 description: "Multiple Pet objects"
6 x-name: "find"
7 responses:
8 "200":
9 description: A list of Pet objects.
10 content:
11 application/json:
12 schema:
13 type: "array"
14 items:
15 $ref: "#/components/schemas/Pet"
Generated Code
1/**
2 * Handles all REST API requests for the endpoint `/pet`.
3 *
4 * @author <AUTHOR>
5 */
6@Model(Pet)
7@Route("/pet")
8class PetRoute extends ModelRoute<Pet> {
9 @Config
10 protected config: any;
11 @Logger
12 protected logger: any;
13
14 @MongoRepository(Pet)
15 protected repo?: Repo<Pet>;
16
17 /**
18 * Initializes a new instance with the specified defaults.
19 */
20 constructor() {
21 super();
22 }
23 ...
24}
Operation Object¶
The following extensions apply to Operation Object definitions.
x-after
¶
Default Value: []
The x-after
field is applied to a Operation Object when it is
desirable to execute one or more middleware functions after the primary endpoint handler has finished. The value
is an array of strings, each being the name of the function to execute.
Example
1 /user:
2 x-schema: User
3 post:
4 description: Create a new User.
5 x-name: create
6 x-before:
7 - validate
8 x-after:
9 - prepareOutput
10 requestBody:
11 content:
12 application/json:
13 schema:
14 $ref: "#/components/schemas/User"
15 responses:
16 "201":
17 description: The newly created User.
18 content:
19 application/json:
20 schema:
21 $ref: "#/components/schemas/User"
Generated Code
1/**
2 * Create a new User.
3 */
4@Auth(["jwt"])
5@Before(["validate"])
6@After(["prepareOutput"])
7@Post()
8private async create(obj: User, @AuthUser user?: JWTUser): Promise<User> {
9 const newObj: User = new User(obj);
10
11 throw new Error("This route is not implemented.");
12}
x-before
¶
Default Value: []
The x-before
field is applied to a Operation Object when it is
desirable to execute one or more middleware functions before the primary endpoint handler has finished. The value
is an array of strings, each being the name of the function to execute.
Example
1 /user:
2 x-schema: User
3 post:
4 description: Create a new User.
5 x-name: create
6 x-before:
7 - validate
8 x-after:
9 - prepareOutput
10 requestBody:
11 content:
12 application/json:
13 schema:
14 $ref: "#/components/schemas/User"
15 responses:
16 "201":
17 description: The newly created User.
18 content:
19 application/json:
20 schema:
21 $ref: "#/components/schemas/User"
Generated Code
1/**
2 * Create a new User.
3 */
4@Auth(["jwt"])
5@Before(["validate"])
6@After(["prepareOutput"])
7@Post()
8private async create(obj: User, @AuthUser user?: JWTUser): Promise<User> {
9 const newObj: User = new User(obj);
10
11 throw new Error("This route is not implemented.");
12}
x-name
¶
Default Value: null
The x-name
field is applied to a Operation Object. It
defines the unique name of the operation and the function name of the generated code for the endpoint handler.
Example
1 paths:
2 /pet:
3 x-schema: Pet
4 get:
5 description: "Multiple Pet objects"
6 x-name: "find"
7 responses:
8 "200":
9 description: A list of Pet objects.
10 content:
11 application/json:
12 schema:
13 type: "array"
14 items:
15 $ref: "#/components/schemas/Pet"
Generated Code
1/**
2 * Multiple Pet objects
3 */
4@Get()
5private async find(@AuthUser user?: JWTUser): Promise<Array<Pet>> {
6 throw new Error("This route is not implemented.");
7}