🧙Dark Magic at Moonfare

Valeriy Kuzmin, Moonfare, Berlin, 2022

Plan

  • Problem
  • Solution overview
  • Implementation details
  • Limitations / future plans

Problem 🧪

  • Api docs...
  • Developers...

Swagger / OpenAPI

/**
  * @swagger
  *
  * /v3/documents/:documentId/download:
  *   get:
  *     description: <truncated>
  *     consumes:
  *       - application/json
  *     produces:
  *       - application/octet-stream
  *     parameters:
  *       - in: path
  *         name: documentId
  *         required: true
  *         type: string
  *     responses:
  *       "200":
  *         description: ok
  *
  * */

Goals 🎯

  • You don't have to write docs → 70%
  • But you can augment generated docs → 100%
  • Docs match code → 80%
  • Docs can be executed → 20%

Solution overview

DTOs

docs/**/*.yaml

@swagger comments

*.swagger.yaml

*.swagger.yaml

*.swagger.yaml

mf_spec.yaml

Controllers

Swaggershift

Implementation details

AST demo - Controller

AST demo - DTO

Pipeline

derive-comments

derive-comments

derive-comments

dto-to-comments

derive-comments

aux.json

derive-comments

swagger.yaml

derive-comments

ast-tools cache

derive-comments

comments + lint

Controller anatomy

@Routing.ApiController(ROUTE_PREFIX_V1, '/root-url/root-2')
class Controller {
  ...
}
  1. Detect by decorator / attribute
  2. Url → Base path

Method anatomy

@Routing.Get('/:id/some-string/:some-other-id(\\d+)')
@Routing.HttpCode(HTTP.OK)
@Routing.Authorized([Roles.DOCUMENT_ADMIN])
@Routing.ContentType('application/json')
public async paramsAndQueryMethod(@Routing.Param('id') _categoryId: number): Promise<{}> {
   ...
}
  1. Detect by decorator → HTTP method
  2. Url → method path + query + path params
  3. ContentType → return type, otherwise json
  4. Signature → params list

Parameter anatomy - query & path

@Routing.Get('/referrals/list/:id')
public async doesNotEatDecorators(
  @Routing.Param('id') id: number,
  @Routing.QueryParam('hint') hint: number,
  @Routing.QueryParam('hint2') hint2: boolean,
  @Routing.QueryParam('order') order: 'ASC' | 'DESC' = 'DESC',
  @Routing.QueryParam('perPage') perPage = DEFAULT_RESULTS_PER_PAGE,
) {
...
}
  1. Names → from strings, not var names
  2. PathParam → always string for now ❗
  3. QueryParam → try deriving ❗
  4. Requiredness → try deriving ❗ 😞 

Parameter anatomy - body & bodyParam

@Routing.Post('/')
@Routing.HttpCode(HTTP.OK)
public async fullBodyMethod(
	@Routing.Body() _body: SomeDTO
): Promise<void> {
   ...
}

@Routing.Put('/')
@Routing.HttpCode(HTTP.OK)
public async virtualBodyMethod(
	@Routing.BodyParam('dtoAsBodyField') _body: SomeDTO
): Promise<void> {
   ...
}
  1. Body → wins over BodyParam
  2. BodyParams → assemble into virtualBody
  3. Any references → write into aux.json
  4. Requiredness → always required ❗ 

Type mapping - params & DTOs

export interface MyInterfaceDTO {
  count: number,
  name: string,
  flag: boolean,
  strangeStuff: Partial<MyTypeDTO>,
}

export type MyTypeDTO = {
  count: number,
  name: string,
  flag: boolean,
  extra: SomeOtherType,
  parts: Array<string>,
};
  1. Unique referenced-by-controllers declarations ❗ 
  2. Primitives → swagger primitives
  3. Auxiliary, Unions, Intersections → #unknown
  4. Complex → $ref, 1 level deep ❗
  5. Built-ins / Externals  → Manually in external.yaml

Testing

// __testfixtures__/name.input.ts
SomeCode

// __testfixtures__/name.output.ts
SomeTransformedCode

// __testfixtures__/name.side-effect.ts
Stuff that is written into files

// .spec
runAsyncTestWithSideEffects(name)
// ❗️ it is possible to pass options to transforms!
  • Input + output formatting is normalized via eslint ❗️
unit-tests:ast-tools

Augmentation & tricks

  1. Generation is wrong? → @swaggershift-ignore, write yourself ✏️
  2. Something is missing or doesn't fit? → Write manually in docs/**/*.yaml 📖
  3. Want it to be auto-generated? → Go improve the tool 🔧 😀
  4. Don't like formatting? → Bother Sergii 🤣 or go write eslint rules with fixes 🔧

Limitations & further plans 💥

  • Missing features
    • Nesting DTOs
    • Enums
    • Some aux types
    • Return shapes
    • Make it invisible 💥
    • Make it typed ❓
  • Related features
    • Some more eslint rules
    • Better autoformatting

https://moonfare.atlassian.net/browse/TD-672

The end!

Questions?

Made with Slides.com