nelsongomes / ts-openapi Goto Github PK

When trying to describe the schema of an ES6 Map, I discovered that arrays of arrays are not yet implemented. Here is a sample:

_specs: Types.Object({
            properties: {
                dataType: Types.String({
                    description: "Must be \"Map\".",
                }),
                value: Types.Array({
                    description: "Array of key/value pairs.",
                    arrayType: Types.Array({
                        description: "Array of length two with the key in the 0th position and the value in the 1st.",
                        arrayType: Types.String()
                    }), 
                }),
            },
            description: "A map with names of agent specs as keys and the spec content as value."
        })

Hey @nelsongomes, thank you for the pretty awsome package. It saves a lot of time when defining an open api. The only thing I didn't get is why it isnt possible to define more than one http method per path. Like, why can I have a post and put to the same endpoint?

Thank you

at openapi.ts line 542 ~ 545

if (requestSchema.body) {
      const { description, schema, example, modelName } = this.bodyParams(
        requestSchema.body
      );
  // ...
}

it calls function bodyParams
at openapi.ts line 944 ~ 951

    return {
      description:
        query.swagger.properties[key].description ||
        "Body does not have a description.",
      schema: this.objectSchema(parameter),
      ...(parameter.example && { example: parameter.example }),
      modelName: parameter.meta.modelName
    };

it calls function objectSchema.
thus when I use array schema as request body, there throws an error at openapi.ts line 213, since parameter.properties is undefined.
for (const propertyKey of Object.keys(parameter.properties)) {

Forgive my clumsy request as I am learning pretty much on all fronts!

I'd like to be able to express that one my schema properties of my response object is a string enumeration. Something like this:

_status: {
    type: "string", 
    enum: ["RUNNING", "COMPLETED", "QUEUED", "ERROR"],
}

I don't think this is possible in the current release of ts-openapi, but it looks like it would fit the openapi specs: https://spec.openapis.org/oas/v3.0.3#schema-object

It'd be awesome if there was a way to tag each enum item with a description, but adding it to the description field of the whole property will suffice.

Currently the readme states:

You can declare:

• get requests
• post requests
• delete requests
• put methods

But this isn't suitable for many APIs that make use of other requests like PATCH, etc.. Any plans on adding support? Would you accept a PR?

EDIT: Open API 3.0 seems to support these:

OpenAPI 3.0 supports get, post, put, patch, delete, head, options, and trace.

I see that version 1.0 added support for schemas, but I'm sort of unsure on how to utilize them.

I've attempted to set a schema like this:

const personSchema = Types.Object({
  properties: {
    id: Types.String(),
    name: Types.String()
  },
  description: "Person object"
})

openApi.checkAndSetSchema("person", personSchema)

I see the resulting json does show a person schema defined correctly. How do I reference this schema I just set under the key person now elsewhere? For now I've just been referencing the variable personSchema I defined for reuse, is that the correct way to go about utilizing a schema model?

I'm very new to openapi so let me know if there's something big I'm missing.

Thanks,

-Themis

How can I add model definitions? I couldn't find it on documentation or any other place.

In 0.3.1, it seems like bodySchema is not exported:

node_modules/ts-openapi/lib/index.js:

"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
var joi_1 = __importDefault(require("joi"));
exports.Joi = joi_1.default;
var openapi_1 = require("./openapi/openapi");
exports.OpenApi = openapi_1.OpenApi;
var auth_1 = require("./openapi/helpers/auth");
exports.basicAuth = auth_1.basicAuth;
exports.apiKeyAuth = auth_1.apiKeyAuth;
exports.bearerAuth = auth_1.bearerAuth;
exports.cookieAuth = auth_1.cookieAuth;
exports.oauth2ImplicitAuth = auth_1.oauth2ImplicitAuth;
exports.oauth2AuthorizationCodeAuth = auth_1.oauth2AuthorizationCodeAuth;
exports.oauth2PasswordAuth = auth_1.oauth2PasswordAuth;
exports.oauth2ClientCredentialsAuth = auth_1.oauth2ClientCredentialsAuth;
var body_mimetype_1 = require("./openapi/helpers/body-mimetype");
exports.textPlain = body_mimetype_1.textPlain;
var types_1 = require("./openapi/helpers/types");
exports.Types = types_1.Types;
//# sourceMappingURL=index.js.map

Yet it was working on the previous version somehow?

I get the following error:

> tsc

source/server/docs/routes.ts:1:26 - error TS2305: Module '"ts-openapi"' has no exported member 'bodySchema'.

1 import { OpenApi, Types, bodySchema, oauth2ClientCredentialsAuth, textPlain } from "ts-openapi";
                           ~~~~~~~~~~
Found 1 error.

Hi,

I'm trying to set an example for a field, however it is not being exported into the final json document. It appears to export correctly for integer values, but not string values. It does however export an example string value correctly when it's within a param and not a response.

const personSchema = Types.Object({
  properties: {
    id: Types.String({example: "example_id"}),  //Does not export example value into json
    authorization: Types.Integer({example: 2})  //Does export example value into json
  },
  description: "Person object"
})

openApi.addPath(
  "/person",
  {
    get: {
      description: "Get person",
      summary: "Gets a person from a group",
      operationId: "get-person",
      responses: {
        200: openApi.declareSchema("person", personSchema)
      },
      tags: ["People"]
    }
  },
true)

Feature request for Types.Map and Types.Set be added to describe the ES6 collections.