You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+15-14Lines changed: 15 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@
11
11
12
12
Document your Serverless Framework API workflows with the [OpenAPI Arazzo Workflow Spec](https://www.openapis.org/arazzo-specification).
13
13
14
-
This will generate an OpenAPI Arazzo Specification (1.0.1) for your Serverless Framework APIs. This requires the [Serverless OpenAPI Documenter](https://github.com/JaredCE/serverless-openapi-documenter) plugin to be installed and used, as the Arazzo Specification makes use of the generated OpenAPI Document.
14
+
This will generate an OpenAPI Arazzo Specification (1.0.1) for your Serverless Framework APIs. This requires the [Serverless OpenAPI Documenter](https://github.com/JaredCE/serverless-openapi-documenter) plugin to be installed and used, as the Arazzo Specification makes use of the generated OpenAPI Document.
15
15
16
16
## Install
17
17
@@ -50,6 +50,7 @@ To run a specification, you should look at:
50
50
## Generating the Arazzo Specification file
51
51
52
52
To generate an Arazzo Specification, you can call the plugin from the CLI like:
53
+
53
54
```bash
54
55
serverless arazzo generate -f json
55
56
```
@@ -78,7 +79,7 @@ custom:
78
79
79
80
See [Configuration via the custom property](#configuration-via-the-custom-property) on how to configure by this method.
80
81
81
-
If you prefer, you might wish to add Configuration on each Handler. You can also seperate the documentation out into a separate file:
82
+
If you prefer, you might wish to add Configuration on each Handler. You can also seperate the documentation out into a separate file:
82
83
83
84
```yml
84
85
custom:
@@ -121,11 +122,11 @@ custom:
121
122
122
123
#### info
123
124
124
-
Mostly everything is optional in the `info` object. If you don't provide a `title`, it'll pull it from your service name, if you don't provide a `version`, it'll default to '1'.
125
+
Mostly everything is optional in the `info` object. If you don't provide a `title`, it'll pull it from your service name, if you don't provide a `version`, it'll default to '1'.
125
126
126
127
#### sourceDescriptions
127
128
128
-
This section is optional. It allows you to document any extra OpenAPI or Arazzo Specification files that your workflows and steps may require. If you do not document this section, it will end up with a default of:
129
+
This section is optional. It allows you to document any extra OpenAPI or Arazzo Specification files that your workflows and steps may require. If you do not document this section, it will end up with a default of:
129
130
130
131
```
131
132
sourceDescriptions:
@@ -136,9 +137,9 @@ sourceDescriptions:
136
137
137
138
That is, that it generates the `name` property from the `title` property of the `info` object (or the one that is generated for you if you omitted the `info` object).
138
139
139
-
The `url` will be that of a local openapi.json file, this is what the [Serverless OpenAPI Documenter](https://github.com/JaredCE/serverless-openapi-documenter) generates by default. This can be changed by the CLI by providing a source argument with the path to a different OpenAPI file. To make this usable, this should really be an accessible URL, so you should switch the `--source` CLI input to be the final resting place of the specification (an S3 bucket perhaps), for running locally it will be fine to keep it as a local location.
140
+
The `url` will be that of a local openapi.json file, this is what the [Serverless OpenAPI Documenter](https://github.com/JaredCE/serverless-openapi-documenter) generates by default. This can be changed by the CLI by providing a source argument with the path to a different OpenAPI file. To make this usable, this should really be an accessible URL, so you should switch the `--source` CLI input to be the final resting place of the specification (an S3 bucket perhaps), for running locally it will be fine to keep it as a local location.
140
141
141
-
If you do provide this section, then any further additions will be added to that of the default `sourceDescription`. This is useful if you need to incorporate a step or workflow that resides in a different API (perhaps a Login service).
142
+
If you do provide this section, then any further additions will be added to that of the default `sourceDescription`. This is useful if you need to incorporate a step or workflow that resides in a different API (perhaps a Login service).
142
143
143
144
#### workflows
144
145
@@ -158,9 +159,9 @@ workflows:
158
159
steps:
159
160
```
160
161
161
-
Workflows comprise of one or many workflow objects, one workflow might be for logging in, another might be for resetting a password. They comprise of steps, where one step might be to call an endpoint to login and the next step would be to call an endpoint that allows a user to change their name.
162
+
Workflows comprise of one or many workflow objects, one workflow might be for logging in, another might be for resetting a password. They comprise of steps, where one step might be to call an endpoint to login and the next step would be to call an endpoint that allows a user to change their name.
162
163
163
-
Each workflow object requires a `workflowId` and a set of `steps`. `workflowId` should conform to the Regex `[A-Za-z0-9_\-]+` and should be unique across the Arazzo Specification.
164
+
Each workflow object requires a `workflowId` and a set of `steps`. `workflowId` should conform to the Regex `[A-Za-z0-9_\-]+` and should be unique across the Arazzo Specification.
164
165
165
166
##### inputs
166
167
@@ -179,7 +180,7 @@ Each workflow object requires a `workflowId` and a set of `steps`. `workflowId`
179
180
type: string
180
181
```
181
182
182
-
The `inputs` here will be used in a login step and can be verified by this JSON Schema. If you are to be usng the runner part of this plugin (see [Running](#running-the-arazzo-specification)), then the inputs should map to the input file (see [Input File](#input-file)).
183
+
The `inputs` here will be used in a login step and can be verified by this JSON Schema. If you are to be usng the runner part of this plugin (see [Running](#running-the-arazzo-specification)), then the inputs should map to the input file (see [Input File](#input-file)).
183
184
184
185
#### steps
185
186
@@ -201,7 +202,7 @@ steps:
201
202
- condition:
202
203
```
203
204
204
-
Each step object requires a `stepId` which conforms to the Regex `[A-Za-z0-9_\-]+`. The `operationId` should point to an `operationId` within an OpenAPI document that is registered within the `sourceDescriptions` array. If you are using multiple OpenAPI files within the `sourceDescriptions` array, then you will need to reference the `operationId` via: `$sourceDescriptions.<name>.<operationId>`e.g.
205
+
Each step object requires a `stepId` which conforms to the Regex `[A-Za-z0-9_\-]+`. The `operationId` should point to an `operationId` within an OpenAPI document that is registered within the `sourceDescriptions` array. If you are using multiple OpenAPI files within the `sourceDescriptions` array, then you will need to reference the `operationId` via: `$sourceDescriptions.<name>.<operationId>`e.g.
205
206
206
207
```yml
207
208
sourceDescriptions:
@@ -295,8 +296,8 @@ custom:
295
296
296
297
This remains the same as what is discussed within [Configuration via the custom property](#configuration-via-the-custom-property).
297
298
298
-
* See [info](#info) for how to document Info
299
-
* See [sourceDescriptions](#sourcedescriptions)
299
+
-See [info](#info) for how to document Info
300
+
-See [sourceDescriptions](#sourcedescriptions)
300
301
301
302
Workflows is where it starts to differ:
302
303
@@ -321,7 +322,7 @@ custom:
321
322
parameters:
322
323
```
323
324
324
-
This still matches up to [workflows](#workflows) (without `steps`). How we document steps, now moves to the handlers:
325
+
This still matches up to [workflows](#workflows) (without `steps`). How we document steps, now moves to the handlers:
325
326
326
327
```yml
327
328
custom:
@@ -375,7 +376,7 @@ Much of this is unchanged from [Steps](#steps), however, we are adding a `stepNu
375
376
376
377
`stepNumber`is the order of which the step should be run, steps start from 1, so the above example would be the first step in the **addPet** workflow.
377
378
378
-
If you don't provide either a `operationId`, `operationPath` or a `workflowId` for the step, the `operationId` will be set to the name of your function. In the above example, the `operationId` would become **addPet**.
379
+
If you don't provide either a `operationId`, `operationPath` or a `workflowId` for the step, the `operationId` will be set to the name of your function. In the above example, the `operationId` would become **addPet**.
0 commit comments