如何使用serverless-aws-documentation插件为无服务器生成带有标签的大型文档 [英] how to generate swagger document with tags using serverless-aws-documentation plugin for serverless

问题描述

我正在使用serverless-aws-documentation插件自动生成swagger-doc.遵循以下位置提供的所有步骤: https://github.com/9cookies/serverless-aws-documentation.在文档密钥下，我正在定义标签，但不会在输出swagger文档中生成它.以下是示例处理程序:

I am using serverless-aws-documentation plugin to auto-generate swagger-doc. Followed all the steps provided at : https://github.com/9cookies/serverless-aws-documentation. Under documentation key I am defining tags but it is not getting generated in the output swagger doc. Following is the sample handler :

functions:
  get_tickets:
    handler: handler.ticket_handler.get_tickets
    events:
      - http:
          path: tickets
          method: get
          cors: true
          documentation:
            tags:
              - private
              - admin
            summary: "Get list of ticket"
            description: "This ticket will provide you list of tickets"

我想根据标签来区分API，但无法实现.预先感谢您的帮助.

I want to segrigate APIs depending on the tags, but not able to achieve it. Thanks in advance for the help.

推荐答案

尝试在serverless.yml中添加 serverless-aws-documentation 插件

Try to add the serverless-aws-documentation plugin in the serverless.yml

plugins:
  - serverless-aws-documentation

在自定义部分中添加infor和模型文档:

Add the infor and models documentation in the custom section:

custom:
  myStage: ${opt:stage, self:provider.stage}
  profiles:
    dev: road-we-go
    prod: road-we-
  documentation:
    info:
      version: "1.0.0"
      name: "Example API"
      description: "Example API description"
      termsOfService: "https://example.com/terms-of-service"
      contact:
        name: "Example API"
        url: "https://example.com"
        email: "[e-mail]"
      licence:
        name: "Licensing"
        url: "https://example.com/licensing"
    models:
      -
        name: "StoreAudioSuccess"
        description: "Model for store audio"
        contentType: "application/json"
        schema: ${file(swagger/audios/storeResponse. 

添加功能文档:

如果要添加诸如 RequestStore 和 StoreAudioSuccess 之类的自定义模型，请检查 serverless-aws-documentation

If you want to add the custom models like RequestStore and StoreAudioSuccess check the serverless-aws-documentation documentation and the json-schema docs

functions:
  Update:
    handler: src/functions/update.handler
    timeout: 30
    memory: 128
    events:
      - http:
         method: put
         private: true
         cors: true
         path: api/v1/update
         documentation:
           summary: "Update "
           description: "Update a record"
           tags:
             - "Users"
           requestModels:
              "application/json": "RequestStore"
           methodResponses:
             -
              statusCode: "200"
              responseModels:
                 "application/json": "StoreUserSuccess"

要下载swagger文档，您需要运行以下命令:

To download the swagger documentation you need to run this command:

首先，您需要部署项目

First you need to deploy you project

sls downloadDocumentation --outputFileName=swagger.json

这篇关于如何使用serverless-aws-documentation插件为无服务器生成带有标签的大型文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！