588 views
   owned this note
# Notifications Project - Swagger documentation ### Plan - Swagger's suite of tools is most oriented towards first specifying an API following OAS and then having its skeleton and documentation generated. Our needs differ from that in the sense that we need only its documentating part, which is generally achieved by annotating code and having the documentation generated. - Our approach should be to follow the Auth team's strategy and adopt a library to help generate documentation from annotations. - What exactly are the examples we should have? - Deploy with results on prof environemnt - Direction right now is to follow with TSOA (listed below on 'Libraries') seems to fit like a glove - Check the attached Medium article. - ![](https://codimd.web.cern.ch/uploads/upload_147e26efb8c95733498d3476b5c877d1.png) - [tsoa has its own guide](https://tsoa-community.github.io/docs/getting-started.html#configuring-tsoa-and-typescript), so far it has been useful - tsoa generates swagger spec succesfully, however, in order to do so, the 'routing-controllers' annotations must be substituted for 'tsoa' annotations, which breaks the code (so far). - tsoa proved incompatible with current 'routing-controlles'. Moving to adoption of another library - [epiphone](https://github.com/epiphone/routing-controllers-openapi), which should handle 'routing-controllers' and generate openAPI spec. - this new adoption has led to a need of somewhat extensive refactoring of the codebase structure. Moving towards using DTOs, no longer exposing internal models. ### Relevant documentation - [Swagger](https://swagger.io/docs/specification/about/) - [OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md) - [Swagger Coding Style Guidelines](https://github.com/watson-developer-cloud/api-guidelines/blob/master/swagger-coding-style.md#introduction) - [Installation/Deployment](https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/) ### Auth team - Auth based on mostly Python and C#. They used Swashbuckle.AspNetCore.SwaggerGen for their C# base. - [Repo](https://gitlab.cern.ch/authzsvc) - [Docs](https://auth.docs.cern.ch/authzsvc/overview/) - Emulate on our "About page". Maybe deploy a [MkDocs site](https://how-to.docs.cern.ch/) too? - [Python Example](https://gitlab.cern.ch/authzsvc/docs/motd-api-example) ### Libraries: - [swagger-jsdoc](https://www.npmjs.com/package/swagger-jsdoc). [Video example](https://www.youtube.com/watch?v=apouPYPh_as) using [swagger.io/specifications](https://swagger.io/specification/) - [swagger-ui-react](https://www.npmjs.com/package/swagger-ui-react) - [swagger-ui-express](https://www.npmjs.com/package/swagger-ui-express) - Typescript oriented libraries? - [typerscript-rest-swagger](https://www.npmjs.com/package/typescript-rest-swagger) - [tsoa](https://github.com/lukeautry/tsoa) can generate Swagger/OpenAPI documents from your TypeScript types. It also does the runtime validation for you so that you know the request actually is the type that TypeScript says it should be. The readme contains all of the setup information that you would need to start using it. It's compatible with express, hapi, koa, and more. [Medium article - using tsoa in a project](https://medium.com/willsonic/swagger-nodejs-typescript-tsoa-15a3f10fabaf) - [redoc](https://github.com/Redocly/redoc): POSSIBLE ALTERNATIVE - [epiphone](https://github.com/epiphone/routing-controllers-openapi) Runtime OpenAPI v3 schema generation for routing-controllers. ### API calls Annotations on [backend](https://gitlab.cern.ch/push-notifications/backend/-/tree/master/src/controllers) to deploy Swagger documentation on https://api-notifications.app.cern.ch/ ### Miscellaneous: - Deploy dev backend example for this? - JSON files in gitlab as endpoints? - Just example property? [Add examples to responses](https://swagger.io/docs/specification/adding-examples/) - jsdoc example (FIRST STEPS): https://github.com/Surnet/swagger-jsdoc/blob/v7/docs/FIRST-STEPS.md - There is a posibility to render the swagger UI on a GitLab repo: - [Render specification on GitLab](https://docs.gitlab.com/ee/user/project/repository/#openapi-viewer) - [Example](https://gitlab.com/gofus/gofus-api/blob/dev/swagger.yaml)