This is the seventh day of my participation in the August More text Challenge. For details, see:August is more challenging

Swagger Document: Swagger. IO /specificati…

Introducing the swagger – the UI

Using koa2 swagger – the UI

const koaSwagger = require("koa2-swagger-ui").koaSwagger; // Import the package app.use(koaSwagger({routePrefix: "/ API /swagger", // write the route to the swagger page: {url: "Swagger. json",// swagger.js file},}));Copy the code

Swagger Configuration file in JSON

There is only one big JSON in the JSON file

The basic configuration

"Openapi" : "3.0.3"Swagger’s version, which is version 3.0.

"info": {}Describes the basic information about the document. Where you can fill"description" 、 "version" 、 "title"These fields.

Ex. :

"Info ": {"description":" iconFont platform node Server ", "version": "1.0.0", "title": "IconFont node Server Interface"},Copy the code

"externalDocs": {}Links can be added to other documents in this document. Where you can fill"description" 、 "url"

"host": "local:3000"Domain name and port for local development

"schemes":["http","https"]Optional protocol for local development

"securityDefinitions"Defining security Policies

Ex. :

  "securityDefinitions": {
    "cookie": {
      "type": "apiKey",
      "name": "cookie",
      "in": "header"
    }
  },
Copy the code

Interface classification

"tags":[]The elements in an array are contains"name"(tag the name of the class) and"description"Object for the field (description of the class).

Ex. :

"Tags" : [{" name ":" user ", "description" : "user interface"}, {" name ":" icon ", "description" : "icon associated interface"}, {" name ": "Atlas ", "description":" icon repository related interface "}, {"name": "project", "description": "project related interface "}],Copy the code

interface

All interfaces are written in the “path”{} field.

For example:

"Path" : {"/API/user/ldap ": {/ / field is the interface" get ": {/ / request method" tags ": / / / the corresponding interface classification" user "], "summary" : "Get ldap for the current user ", // interface description" description":" get ldap for the current user ", // interface description" operationId": "login", // operationId (only function) "responses": {/ / return conditions of "200" : {" description ":" ok "}, "401" : {" description ":" not login, no permissions "}}}}Copy the code

The get method takes arguments

"/ API /project/detail/{id}": {// get": {"tags": ["project"], "summary": "get details ", "description": "Return project details ", "operationId": "getMyProjectDetail", "parameters": [// url with parameter description {"name": "id", // corresponding url with curly brace id" in": "Require ": true, "schema": {// Describe the type of the parameter "type": "Integer"}}], "responses" : {" 200 ": {" description" : "ok"}, "401" : {" description ":" not login, no permissions "}}}},Copy the code

Basic POST method

"/ API /project/search": {"post": {// post method "tags": ["project"], "summary": "search project", "description": "Return possible project ", "operationId": "searchMyProject", "requestBody": {// Request parameter "description":" input name ", // Request parameter description" content": {// Request content "application/json": {// Request parameter type" schema": {// Description request parameter type" type": "object", "properties": {// Included attribute "projectName": {"type": "string"}}}}}, "required": true}, "responses": {"200": {"description": "Ok"}, "401" : {" description ":" not login, no permissions "}}}}}Copy the code

Post comes with the upload file

"/ API /icon/create": {"post": {"tags": ["icon"], "Summary ":" upload icon", "Description ":" Return the updated atlas ", "operationId": "AddIcon ", "requestBody": {"description": "icon's content and atlas ID "," Content ": {"multipart/form-data": {"schema": {"type": "object", "properties": { "atlasId": { "type": "number" }, "icon": { "type": "string", "format": "Binary" / / if the file, so write}}}}}, "required" : true}, "responses" : {" 200 ": {" description" : "ok"}, "401" : {"description": "no login, no permission"}}}},Copy the code

When the file is transferred to the back end, it will be mounted under ctx.request.files. We can get the icon file we uploaded from ctX.request.files.icon.

A uniform way of writing data structures

Write in “components”: {“schemas”:{}}

Components ":{"schemas":{"UserModel": {"type": "object", "properties": {"id": {"type": "integer", "format": "int64" }, "ldapId": { "type": "string" } } }, }}Copy the code

Usage:

"/ API/project/create" : {" post ": {" tags" : [" the project "], "summary" : "new project", "description" : "Return the updated project I managed and the project I participated in ", "operationId": "createMyProject", "requestBody": {"description": "$ref", "content": {"application/json": {"schema": {"$ref": {"application/json": {"schema": {"$ref": "# / components/schemas/ProjectModel" / / in schema field is $ref said reference, content for path}}}, "required" : true}, "responses" : {" 200 ": } {" description ":" ok ", "401" : {" description ":" not login, no permissions "}}}},Copy the code