Skip to content

Commit 74f3f66

Browse files
authored
Merge pull request #19 from JaredCE/prettify
prettifies everything
2 parents 4395952 + a164be4 commit 74f3f66

File tree

14 files changed

+2368
-2058
lines changed

14 files changed

+2368
-2058
lines changed

README.md

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
Document your Serverless Framework API workflows with the [OpenAPI Arazzo Workflow Spec](https://www.openapis.org/arazzo-specification).
1313

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.
1515

1616
## Install
1717

@@ -50,6 +50,7 @@ To run a specification, you should look at:
5050
## Generating the Arazzo Specification file
5151

5252
To generate an Arazzo Specification, you can call the plugin from the CLI like:
53+
5354
```bash
5455
serverless arazzo generate -f json
5556
```
@@ -78,7 +79,7 @@ custom:
7879

7980
See [Configuration via the custom property](#configuration-via-the-custom-property) on how to configure by this method.
8081

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:
8283

8384
```yml
8485
custom:
@@ -121,11 +122,11 @@ custom:
121122

122123
#### info
123124

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'.
125126

126127
#### sourceDescriptions
127128

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:
129130

130131
```
131132
sourceDescriptions:
@@ -136,9 +137,9 @@ sourceDescriptions:
136137

137138
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).
138139

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.
140141

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).
142143

143144
#### workflows
144145

@@ -158,9 +159,9 @@ workflows:
158159
steps:
159160
```
160161

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.
162163

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.
164165

165166
##### inputs
166167

@@ -179,7 +180,7 @@ Each workflow object requires a `workflowId` and a set of `steps`. `workflowId`
179180
type: string
180181
```
181182

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)).
183184

184185
#### steps
185186

@@ -201,7 +202,7 @@ steps:
201202
- condition:
202203
```
203204

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.
205206

206207
```yml
207208
sourceDescriptions:
@@ -295,8 +296,8 @@ custom:
295296

296297
This remains the same as what is discussed within [Configuration via the custom property](#configuration-via-the-custom-property).
297298

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)
300301

301302
Workflows is where it starts to differ:
302303

@@ -321,7 +322,7 @@ custom:
321322
parameters:
322323
```
323324

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:
325326

326327
```yml
327328
custom:
@@ -375,7 +376,7 @@ Much of this is unchanged from [Steps](#steps), however, we are adding a `stepNu
375376

376377
`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.
377378

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**.
379380

380381
## Validator
381382

index.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
const ArazzoPlugin = require('./src/ArazzoPlugin')
1+
const ArazzoPlugin = require("./src/ArazzoPlugin");
22

3-
module.exports = ArazzoPlugin
3+
module.exports = ArazzoPlugin;

0 commit comments

Comments
 (0)