From 2970f74986a71b944b87b6214112ebf7ead7602f Mon Sep 17 00:00:00 2001 From: Frazer Smith Date: Sat, 11 Jan 2025 09:39:13 +0000 Subject: [PATCH] docs(readme): spelling and grammar fixes (#853) Signed-off-by: Frazer Smith --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index ecfb00dc..0a72fe3b 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,16 @@ [![CI](https://github.com/fastify/fastify-swagger/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/fastify/fastify-swagger/actions/workflows/ci.yml) [![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard) -A Fastify plugin for serving [Swagger (OpenAPI v2)](https://swagger.io/specification/v2/) or [OpenAPI v3](https://swagger.io/specification) schemas, which are automatically generated from your route schemas, or from an existing Swagger/OpenAPI schema. +A Fastify plugin for serving [Swagger (OpenAPI v2)](https://swagger.io/specification/v2/) or [OpenAPI v3](https://swagger.io/specification) schemas, which are automatically generated from your route schemas, or an existing Swagger/OpenAPI schema. If you are looking for a plugin to generate routes from an existing OpenAPI schema, check out [fastify-openapi-glue](https://github.com/seriousme/fastify-openapi-glue). -Following plugins serve Swagger/OpenAPI front-ends based on the swagger definitions generated by this plugin: +The following plugins serve Swagger/OpenAPI front-ends based on the swagger definitions generated by this plugin: - [@fastify/swagger-ui](https://github.com/fastify/fastify-swagger-ui) - [@scalar/fastify-api-reference](https://github.com/scalar/scalar/tree/main/packages/fastify-api-reference) -See also [the migration guide](MIGRATION.md) for migrating from `@fastify/swagger` version <= `<=7.x` to version `>=8.x`. +See [the migration guide](MIGRATION.md) for migrating from `@fastify/swagger` version <= `<=7.x` to version `>=8.x`. ## Install @@ -43,7 +43,7 @@ See [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Ref ## Usage -Add it to your project with `register`, pass it some options, call the `swagger` API, and you are done! Below an example of how to configure the OpenAPI v3 specification with Fastify Swagger: +Add it to your project with `register`, pass it some options, call the `swagger` API, and you are done! Below is an example of how to configure the OpenAPI v3 specification with Fastify Swagger: ```js const fastify = require('fastify')() @@ -135,7 +135,7 @@ fastify.swagger() ### With `@fastify/autoload` -You need to register `@fastify/swagger` before registering routes. +You need to register `@fastify/swagger` before registering routes: ```js const fastify = require('fastify')() @@ -205,7 +205,7 @@ Examples of using `@fastify/swagger` in `dynamic` mode: ##### Static - `static` mode must be configured explicitly. In this mode `@fastify/swagger` serves an already existing Swagger or OpenAPI schema that is passed to it in `specification.path`: + `static` mode must be configured explicitly. In this mode, `@fastify/swagger` serves an already existing Swagger or OpenAPI schema that is passed to it in `specification.path`: ```js { @@ -224,7 +224,7 @@ The `specification.postProcessor` parameter is optional. It allows you to change It accepts `swaggerObject` - a JavaScript object that was parsed from your `yaml` or `json` file and should return a Swagger schema object. `specification.baseDir` allows specifying the directory where all spec files that are included in the main one using `$ref` will be located. -By default, this is the directory where the main spec file is located. Provided value should be an absolute path **without** trailing slash. +By default, this is the directory where the main spec file is located. The provided value should be an absolute path **without** a trailing slash. An example of using `@fastify/swagger` with `static` mode enabled can be found [here](examples/static-json-file.js). @@ -246,14 +246,14 @@ An example of using `@fastify/swagger` with `static` mode enabled can be found [ #### Transform -By passing a synchronous `transform` function you can modify the route's url and schema. +By passing a synchronous `transform` function you can modify the route's URL and schema. You may also access the `openapiObject` and `swaggerObject` Some possible uses of this are: -- add the `hide` flag on schema according to your own logic based on url & schema -- altering the route url into something that's more suitable for the api spec +- add the `hide` flag on schema according to your own logic based on URL & schema +- altering the route URL into something that is more suitable for the API spec - using different schemas such as [Joi](https://github.com/hapijs/joi) and transforming them to standard JSON schemas expected by this plugin - hiding routes based on version constraints @@ -315,7 +315,7 @@ If both a global and a local transform function is available for an endpoint, th The local transform function can be useful if you: - want to add additional information to a specific endpoint -- have an endpoint which requires different transformation from other endpoints +- have an endpoint that requires a different transformation from other endpoints - want to entirely ignore the global transform function for one endpoint The endpoint-specific transform can be used to "disable" the global transform function by passing in `false` instead of a function. @@ -340,7 +340,7 @@ await fastify.register(require('@fastify/swagger'), { #### Managing your `$ref`s When this plugin is configured as `dynamic` mode, it will resolve all `$ref`s in your application's schemas. -This process will create an new in-line schema that is going to reference itself. +This process will create a new in-line schema that is going to reference itself. This logic step is done to make sure that the generated documentation is valid, otherwise the Swagger UI will try to fetch the schemas from the server or the network and fail. @@ -360,7 +360,7 @@ await fastify.register(require('@fastify/swagger'), { } ``` -To deep down the `buildLocalReference` arguments, you may read the [documentation](https://github.com/Eomm/json-schema-resolver#usage-resolve-one-schema-against-external-schemas). +For a deep dive into the `buildLocalReference` arguments, you may read the [documentation](https://github.com/Eomm/json-schema-resolver#usage-resolve-one-schema-against-external-schemas). #### Decorator @@ -642,7 +642,7 @@ As far as arrays are concerned, the default query string parser conforms to the If you were to select `collectionFormat: "csv"`, you would have to replace the default query string parser with one that parses CSV parameter values into arrays. The same applies to the other parts of a request that OpenAPI calls "parameters" and which are not encoded as JSON in a request. -You can also apply different serialization `style` and `explode` as specified [here](https://swagger.io/docs/specification/serialization/#query). +You can also apply a different serialization `style` and `explode` as specified [here](https://swagger.io/docs/specification/serialization/#query). `@fastify/swagger` supports these options as shown in this example: @@ -846,7 +846,7 @@ Will generate this in the OpenAPI v3 schema's `paths`: } ``` -Whether `params` is not present in the schema, or a schema is not provided, parameters are automatically generated, for example: +When `params` is not present in the schema, or a schema is not provided, parameters are automatically generated, for example: ```js fastify.route({ @@ -1150,7 +1150,7 @@ fastify.route({ ## Development -In order to start development run: +To start development run: ``` npm i npm run prepare @@ -1164,9 +1164,9 @@ So that [swagger-ui](https://github.com/swagger-api/swagger-ui) static folder wi #### How to work with $refs -The `/docs/json` endpoint in dynamic mode produces a single `swagger.json` file resolving all your +The `/docs/json` endpoint in dynamic mode produces a single `swagger.json` file resolving all your references. -## Acknowledgements +## Acknowledgments This project is kindly sponsored by: - [nearForm](https://nearform.com)