“This article is participating in the technical topic essay node.js advanced road, click to see details”

In the article “Building API services with Node.js, MongoDB, and Fastify”, we introduce Swagger to build API documentation. Writing documentation is not so easy. Here we introduce another way of writing API documentation, using Yaml, that completely separates API documentation from its implementation.

The article continues to iterate on the project restful API, starting with a brief look at Yaml.

What is a Yaml

YAML is a file format commonly used for data serialization. Many projects use YAML files for configuration. Common examples are Docker-compose, ESLint, Kubernetes, and so on. Originally representing Yet Another Markup Language, it was later changed to YAML Ain’t Markup Language to distinguish it from the real Markup Language.

It is similar to XML and JSON files, but uses a more minimalist syntax, even while maintaining similar functionality. YAML is a superset (source) of JSON, and every valid JSON file is also a valid YAML file. The previous Swagger document requires building a JSON data to take advantage of YAML’s feature.

YAML files use a Python-like indentation system to display the structure of a program, requiring Spaces instead of tabs to create indentation to avoid confusion.

Writing Yaml

Create the file api.yaml in the project directory SRC /docs and add the following code:

Openapi: 3.0.1 Info: Description: This is an API about the type of coffee. Title: Coffee Restful API version: 1.0.0 servers: - description: the Main server url: http://localhost:8100/api/v1 paths: /coffees: get: operationId: coffeesGET responses: "200": content: application/json: schema: items: $ref: "#"/components/schemas/Coffee type: array x - the content-type: application/json description: successful description: Summary: Get a list of all coffee types Tags: - Coffees Post: operationId: coffeesPOST requestBody: Content: Application /json: schema: $ref: "#/components/schemas/CoffeeRequest" responses: "200": content: application/json: schema: items: $ref: "#"/components/schemas/Coffee type: array x - the content-type: application/json description: create success the description: Summary: Create a new type of coffee Tags: - Coffees/Coffees /{id}: get: operationId: coffeesIdGET parameters: - description: Id explode: false in: path name: ID required: true schema: type: string style: simple responses: "200": content: Application/json: schema: $ref: "# / components/schemas/Coffee" description: for more details description: success by id get Coffee species details the summary: Tags: -coffees delete: operationId: coffeesIdDELETE parameters: -description: coffeesIdDELETE id explode: false in: Path name: ID required: true schema: Type: string style: simple responses: "204": description: Deleted successfully Description: Delete coffee type details by ID Summary: Delete coffee type details tags: - Coffees put: operationId: coffeesIdPUT parameters: - description: Id explode: false in: path name: ID required: true schema: type: string style: Simple requestBody: Content: application/json: schema: $ref: "#/components/schemas/CoffeeRequest" responses: "201": content: application/json: Schema: $ref: "# / components/schemas/Coffee" description: updated description: Coffee species by id to update the summary: Coffee species update tags: - Coffees components: schemas: Coffee: example: _id: id title: title ratio: ratio cup: cup description: description properties: _id: maxLength: 24 minLength: 24 type: string title: type: string ratio: type: string cup: type: string description: type: string type: object CoffeeRequest: example: title: "Red Eye" ratio: "1 shot of espresso" cup: "8 oz. Coffee Mug" description: description properties: title: type: string ratio: type: string cup: type: string description: type: string type: objectCopy the code

Modify the configuration SRC /config/swagger.js as follows:

exports.options = {
    routePrefix: "/api/v1/helper",
    exposeRoute: true,
    yaml: true,
    mode: "static",
};
Copy the code

Delete the information related to the document in the route and modify the file SRC /routes/index.js. The complete code is as follows:

const coffeeController = require(".. /controllers/coffeeController"); const APIPATH = "/api/"; const VERSION = "v1"; const ENDPOINT = "/coffees"; const getFullPath = (method = "") => `${APIPATH}${VERSION}${ENDPOINT}${method}`; const routes = [ { method: "GET", url: getFullPath(), handler: coffeeController.getList, }, { method: "GET", url: getFullPath("/:id"), handler: coffeeController.get, }, { method: "POST", url: getFullPath(), handler: coffeeController.add, }, { method: "PUT", url: getFullPath("/:id"), handler: coffeeController.update, }, { method: "DELETE", url: getFullPath("/:id"), handler: coffeeController.delete, }, ]; module.exports = routes;Copy the code

Modify the entry file SRC /index.js, mainly to modify the swagger part as follows:

fastify.register(require("fastify-swagger"), { ... swagger.options, specification: { path: path.join(__dirname, "./docs", "api.yaml"), postProcessor: function (swaggerObject) { return swaggerObject; ,}}});Copy the code

After running, open the API documentation path and see the following:

Source code address: restful API