서비스 중복 제거: Swagger/OpenAPI 및 AJV

25446 단어 microservicesjavascriptopenapibackend
좋은 디자인은 바꾸기 쉽다.그러나 API 문서 및 서비스 검증과 관련하여 ETC의 이러한 원칙은 간과되는 경우가 많습니다.여기서 Do Not Repeat Yourself[DRY]의 세입자들은 수백 줄(수천 줄이 아니라면) 코드를 넘을 수 있는 여러 개의 파일과 대량의 중복을 남기는 경우가 많다.
단일 검증 엔진과 시장 문서를 흔드는 서비스 개발은 뒤이어 기술 채무 형식이 되었다.이러한 엔진과 문서는 통상적으로 변경되고 있는 코드 표면 영역 밖에 있기 때문에 동기화되지 않을 가능성이 증가한다.

그럼 해결책은 뭐예요?


나는 당신의 흔들림 문서를 개발하고 OpenAPI 규범에 따라 검증을 구동할 수 있는 새로운 디자인 모델을 제시했다.
위에서 언급한 우리의 사명 성명에서, 우리 모두가 우리의 도구 체인과 같은 페이지에 서 있도록 확보합시다.NodeJS와 자바스크립트 생태계가 바로 이렇다. 이것은 우리의 최종 목표를 이해하는 중요한 걸음이다.
Service Documentation: Swagger 3.0 -- OpenAPI

Service Validation Engine: AJV

node-modules: swagger-jsdoc, openapi-validator-middleware

NodeJS Framework: Express
다른 검증 엔진(JOI와express validator, 몇 가지 예를 들면)이 존재한다는 것을 인정하지만 AJV는 간단한 JSON 요약을 제공했고 사람들이 OpenAPI 패키지를 작성했습니다!NodeJS 프레임워크에 관해서는 express를 사용합니다. 왜냐하면 이것은 제가 더 잘 알고 있기 때문입니다.이 패키지openapi-validator-middleware는 심지어 koa를 지원하기 때문에 koa에 적용되지 않을 이유가 없습니다!

그렇다면 당신은 도대체 어떻게 중복을 없앨 수 있습니까?


상기 가방마다 특정한 목표가 있습니다.swagger-jsdoc에 대해 우리는 앞의 견해, 즉 바꾸기 쉽다는 것을 견지할 것이다.우리는 루트 파일에서 우리의 흔들림 정의를 공동으로 포지셔닝할 것이다.이것은 미래의 개발자들이 코드와 공존하는 규범을 보게 하고 그들이 노선에서 코드를 변경할 때 이 규범을 바꾸어야 한다는 것을 더욱 분명하게 보게 할 것이다.openapi-validator-middleware 생성된 OpenAPI Swagger 문서를 사용하여 검증 엔진에 사용할 수 있습니다.이 패키지는 AJV를 둘러싼 패키지입니다. 이 패키지는 대량의 중복을 없애기 위해 코드를 최소화할 수 있습니다.

이게 무슨 모양이야?


따라서 검증 부분부터 시작해서 파일 응용 프로그램을 살펴보겠습니다.우리는 여기에express 프로그램을 설명합니다.
먼저 해야 할 일모듈을 가져오라고 하시네요.
const swaggerValidation = require('openapi-validator-middleware');
가져오면 Swagger 설명서를 가리키기만 하면 구성할 수 있습니다.
swaggerValidation.init('swagger.yml');
Google swagger 설정 검증 엔진을 사용하면 루트 정의에서 이를 중간부품으로 실행하기만 하면 됩니다.
api.get('/simple', swaggerValidation.validate, getSimple)
이 세 줄 코드가 있으면, 우리는 검증 엔진을 설정하여, 이를 우리의 시장 규범으로 조정하고, 현재/simple 루트에 대한 규칙을 실행하고 있다.서비스 인증을 유지하기 위한 별도의 파일 Joi/AJV 파일 유지 관리 불필요 - 멋있죠?

그래, 그런데 거들먹거리는 서류는?이거 무섭지 않아요?


답은 긍정적이다.너의 거들먹거리는 서류는 지금 너의 모든 검증 논리가 있어야 하기 때문에 그것은 거대할 것이다 - 하지만 이미 이런 정보가 있을 거예요.따라서 이 점을 감안하여 우리는 다른 패키지 swagger jsdoc로 하여금 swagger 파일을 유지하는 것을 걱정하게 할 것이다.우리의 목표는 더 쉽게 바뀐다. 기억나?따라서, 우리는 우리의 흔들림 정의를 루트 파일 논리와 함께 놓을 것이다.개발자가 변경할 때 코드와 문서가 같은 곳에 있기 때문에 그들은 모든 내용을 동기화할 수 있도록 더 많은 격려를 받기를 바란다.매개 변수/요청 기구의 검증 요구를 변경하는 것은 말할 것도 없고, 모든 요구도 swagger 문서에 즉시 반영됩니다.
다음은 우리의 간단해짐이다.우리가 정의한 js
/**
 * @openapi
 *  /v1/acme:
 *    get:
 *      description: a simple get route that returns the `foo` query param
 *      parameters:
 *        - in: query
 *          name: foo
 *          schema:
 *            type: string
 *            minimum: 3
 *      responses:
 *        200:
 *          description: a object witth the echoed query param.
 *          content:
 *            type: object
 *            properties:
 *              foo:
 *                type: string
 *                minimum: 3
 */
const getSimple = (req, res) => {
  const { foo } = req.query;
return res.status(200).json({ foo });
};
module.exports = getSimple;

잠깐만, 문제가 좀 있어!


Is that 20 lines of comments for a 4 line route file? And how come foo is duplicated I thought we were removing duplication?


이 문제들에 대답해야 한다. 네, 여기 대량의 문서가 있습니다.이것은 피할 수 없는 것이다. 왜냐하면 우리는 이곳에서 거들먹거려야 하기 때문이다. 그러나 이것은 새로운 개발자가 이 파일을 보고 요청과 응답에 대한 기대를 파악하는 데 도움이 될 것이다.
네가 본 복제품에 관해서 나는 곧 시작할 것이다.복제품을 쉽게 전시하기 위해서다.YAML의 특성을 사용하면 우리는 실제적으로 중복을 없애고 우리의 정의를 더욱 구분할 수 있다.

좋아요. - 시작해 봐, 어떻게 했어?


YAML 앵커를 사용하면 필드의 원자 정의와 같은 변수를 만들 수 있습니다.그러나 우선, 우리는 우리의 서비스에 대해 더 많은 구축을 하고, 파일/디렉터리를 만들 것이다.
mkdir swagger
touch swagger/first-name.yml
touch swagger/last-name.yml
touch swagger/user-id.yml
보시다시피 이 swagger 폴더는 우리의 모든 swagger 구성 요소 정의를 포함합니다.따라서 모든 경로에서 일관된 정의를 유지하면서 현재 진리의 원천을 공유할 수 있기 때문에 중복을 없앨 수 있다 - 이 폴더는

파일


# swagger/first-name.yml
x-template:
  firstName: &firstName
    type: string
    minimum: 1
    maximum: 30
    description: the first name of our acme user
# swagger/last-name.yml
x-template:
  lastName: &lastName
    type: string
    minimum: 1
    maximum: 30
    description: the last name of our acme user
# swagger/user-id.yml
x-template:
  userId: &userId
    type: string
    minimum: 4
    maximum: 4
    pattern: '[0-9]{4}'
    description: the unique identifier of our acme user
우리의 흔들림 필드 구성 요소가 생성됨에 따라, 우리는 우리의 새로운 필드를 사용하여 새로운 노선을 회전할 것입니다.

그것을 넣고 창조해라.js


/**
 * @openapi
 *  /v1/acme/create:
 *    put:
 *      description: creates a fake user of the acme service
 *      requestBody:
 *        content:
 *          application/json:
 *            schema:
 *              type: object
 *              required:
 *                - firstName
 *                - lastName
 *              properties:
 *                firstName: *firstName
 *                lastName: *lastName
 *      responses:
 *        200:
 *          description: a object with the echoed firstName, lastName and a random userId.
 *          content:
 *            type: object
 *            properties:
 *              firstName: *firstName
 *              lastName: *lastName
 *              userId: *userId
 */
const putCreate = (req, res) => {
  const { firstName, lastName } = req.body;
  const userId = Math.floor(1000 + Math.random() * 9000);
return res.status(200).json({ firstName, lastName, userId: `${userId}` });
};
module.exports = putCreate;
이것 봐, 우리는 이미 더 복잡한 요청/응답 대상을 만들었어, 우리의 평론 줄 총수는 아직 3줄이 있어!가장 중요한 것은 이 파일에 대해 경험이 없어도 첫 번째 논평을 읽어서 그 용례와 요청/응답 계약을 확인할 수 있다는 것이다.바뀌기 쉬운 장점 보이시나요?만약 60글자의 성씨를 허용해야 한다면, swagger 파일의 성씨를 간단하게 변경할 수 있습니다.yml 및 업데이트된 Swagger 문서와 검증 규칙을 실행합니다!

좋아요. - 나는 설득을 당했지만, 너는 어떻게 이 평론들을 거들먹거리는 의사로 변하게 했니?


거들먹거리는 발전기.mjs


import fs from 'fs';
import swaggerJsdoc from 'swagger-jsdoc';
import { dirname } from 'path';
import { fileURLToPath } from 'url';
import packageJson from './package.json';
const __dirname = dirname(fileURLToPath(import.meta.url));
const options = {
  format: '.yml',
  definition: {
    openapi: '3.0.0',
    info: {
      title: packageJson.name,
      version: packageJson.version,
    },
  },
  apis: ['./src/routes/*.js', './swagger/**/**.yml'], // files containing annotations
};
const runtime = async () => {
  try {
    const openapiSpecification = await swaggerJsdoc(options);
    fs.writeFileSync(`${__dirname}/swagger.yml`, openapiSpecification);
  } catch (e) {
    console.log('broke', e);
  }
};
runtime();
위의 스크립트는 OpenAPI 사양을 생성하고 자랑을 생성하는 마법입니다.검증 엔진이 소모할yml입니다.좋은 실천을 돕고 모든 개발자(나 포함)가 기억을 잘하지 못하기 때문에 저는 개인적으로 Husky를 이용하여 이 파일을 생성할 수 있습니다.이것은 위의 스크립트를 실행한 다음 git add Swigger 를 실행하는 사전 제출 갈고리로 완료됩니다.yml 명령.

그런데 어떻게 그걸 할 수 있어요?


CI CI!우리는 자랑을 하기 위해 미리 제출한 갈고리가 하나밖에 없기 때문이다.yml, 합리적인 우려가 있습니다.문서가 없는 것보다 더 나쁜 유일한 것은 엉망/유행이 지난 문서이다.

What if a developer commits with a -n or simply makes the commit from the web-ui


우선, 나는 그들이 괴물이라고 말한다(특히 그들이 -n을 사용한다면!).그러나 이를 실현하기 위해서는 프로그램을 만들거나 귀속할 때 구축 절차가 되어야 한다.테스트 용례를 통해 우리는 swaggerJsDoc 명령을 다시 실행하고 출력을 swagger.yml 출력과 직접 비교할 수 있다.어떠한 불일치도 집행을 중지한다.

예제/참조 자료


환매 협의는 이 과정을 보여 주었다.


고르즈지 / ms acme openapi ajv



ms acme openapi ajv


기사 링크:
https://gem-ini.medium.com/de-duping-the-duplication-in-services-featuring-swagger-openapi-and-ajv-abd22c8c764e
환매 협의의 목적은 언론 기사의 조수가 되는 것이다.비밀 번호
본 환매 협의는 개인의 생산 품질 코드를 대표하지 않는다
코드 샘플은 보류되어 있어야 하지만, 패턴 자체는 잘못된 것이다
뭘 검사해야 되는데?

패턴


이 환매 협의는 너에게 어떻게 너의 흔들리는 서류를 너의 택배 노선과 함께 두는지 보여 주었다
서류철.이 공동 포지셔닝이 있으면, 우리는 미리 제출한 갈고리를 만들어 낼 수 있다
거들먹거리는 출력.그리고 이 흔들리는 출력은 검증 파일이 될 것이다
이것은 당신의 빠른 노선을 보호할 것입니다. (더 자세한 정보는 글 참조)
View on GitHub

사용된 패키지


수르네트 / 거들먹거리다


swagger/openapi 사양은 jsDoc 주석 및 YAML 파일을 기반으로 생성됩니다.


거들먹거리다


이 라이브러리는 JSDoc 주석의 원본 코드를 읽고 생성OpenAPI (Swagger) specification합니다.


개시하다


다음과 같은 API 파일이 있다고 생각해 보십시오.
/**
*@openapi
*/:
* 제공:
* 스웨그jsdoc에 오신 것을 환영합니다!
* 답변:
* 200:
* 설명: 신비한 문자열을 되돌려줍니다.
*/
응용 프로그램.얻기("/",(요청, 회신)=>{
res.send('Hello World!');
});
라이브러리는 다음과 같은 구성으로 @openapi(또는 @swagger) 컨텐츠를 가져옵니다.
const-swagger-jsdoc=require('swagger-jsdoc');
상수 옵션 =
정의:
openapi:'3.0.0',
정보:
제목: "안녕하세요, 세계",
버전: "1.0.0",
},
},
API: ['./src/routes*.js'],//위의 주석이 포함된 파일
};
const openapiSpecification=swaggerJsdoc(옵션),
결과openapiSpecification는swagger...
View on GitHub

파우 / openapi 검증 프로그램 중간부품


Swagger(오픈 API) 및 ajv를 사용한 입력 검증


openapi 검증 프로그램 중간부품








aSwagger/OpenAPI definition에 따르면 이 패키지는 Express, Koa 또는 Fastify 애플리케이션에서 데이터 인증을 제공합니다.그것은 엔진 덮개 아래에서 사용Ajv으로 검증되었다.
주의: 이 가방은 긴 과정을 거쳤기 때문에 OpenAPI에 대한 지원을 추가했고 더 많은 프레임워크 (예를 들어 Koa와Fastify) 에 대한 지원도 추가했습니다. 최종적으로 express-ajv-swagger-validation 명칭을 더 잘 설명하는 것으로 변경하는 절차를 취했습니다.지금까지 우리는 명칭openapi-validator-middleware을 사용할 것이다.[email protected]에 비해 [email protected]에는 이름 변경 외에 코드 변경이 없다.
카탈로그

  • openapi-validator-middleware
  • Installation

  • API

  • openapi-validator-middleware.validate(fastifyOptions)
  • fastifyOptions
  • openapi-validator-middleware.init(pathToSwaggerFile, options)

  • openapi-validator-middleware.initAsync(pathToSwaggerFile, options)
  • Options

  • Usage Example
  • Express
  • Koa
  • Fastify
  • Multiple-instances

  • Important Notes
  • Schema Objects
  • Multipart/form-data (files)
  • Fastify support
  • Koa support
  • Koa packages
  • Known Issues with OpenAPI 3
  • Running Tests

    • 장치


    노드 패키지 레지스트리를 사용하여 설치하려면 다음과 같이 하십시오.
    npm 설치 - openapi 검증 프로그램 중간부품을 저장합니다
    모듈을 가져오는 중...
    View on GitHub
    [NOIP2000TG/codevs1017] 곱하기 최대 문제풀이 보고서
    uva 10118(DP)

    좋은 웹페이지 즐겨찾기

    개발자 우수 사이트 수집

    개발자가 알아야 할 필수 사이트 100선 추천 우리는 당신을 위해 100개의 자주 사용하는 개발자 학습 사이트를 정리했습니다
    best100-homepage