Documentation

[alichampion]

Very Poor documentation!

No example of how to use it.

@pjmolina please at least attach an example.

After searching a lot I got this code sandbox example.

https://codesandbox.io/s/olpj88zyly?file=/src/index.ts

[svrakata]

You can build schema. Example:

import { OpenApiBuilder, PathsObject, PathItemObject, ResponseObject } from "openapi3-ts";
import apiConfig from "./config";

const getUserResponse: ResponseObject = {
    description: "Gets user info by user id.",
}

const user: PathItemObject = {
    get: {
        operationId: "user",
        responses: {
            "200": getUserResponse,
        }
    }
}

const paths: PathsObject = {
    "/user": user,
}

const builder = OpenApiBuilder.create({
    openapi: apiConfig.openAPIVersion,
    info: {
        title: apiConfig.title,
        version: apiConfig.version,
        description: apiConfig.description,
        contact: apiConfig.contact,
    },
    paths,
    servers: [
        {
            url: `${apiConfig.host}:${apiConfig.port}`,
        },
    ],
});

builder.addPath("/articles", {
    get: {
        operationId: "articles",
        responses: {
            "200": {
                description: "Gets all articles.",
            },
        },
        parameters: [
            {
                name: "page",
                in: "query",
            },
        ],
    },
});

export const definition = builder.getSpec(); // js object
export const definitionJson = builder.getSpecAsJson(); // json
export const definitionYaml = builder.getSpecAsYaml(); // yaml

[strazto]

Very Poor documentation!

No example of how to use it.

I mean yea.

Kinda surprising that no-one has even tried to contribute documentation given that this project seems to have like 550k weekly installs

[pjmolina]

Thanks for the time taken to prepare and example @svrakata (we can use it as the seed for minimal docs). As you all know, documentation like any other feature requires time. Unit tests provided are a good source for documentation. PR are open and therefore, contributions are welcome. Thank you in advance.

[CaptainYarb]

The lack of documentation has now even made these comments out of date.

[rddyck]

https://codesandbox.io/s/olpj88zyly?file=/src/index.ts

So. someone who is trying to learn what all it can do and how to use it is responsible for creating documentation?

[pjmolina]

Added some basic docs on PR #139 Feel free to ask for anything else, or better, add a PR to improve it.