Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation #75

Open
alichampion opened this issue Mar 22, 2022 · 6 comments
Open

Documentation #75

alichampion opened this issue Mar 22, 2022 · 6 comments

Comments

@alichampion
Copy link

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
Copy link

svrakata commented May 2, 2022

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
Copy link

strazto commented Jul 21, 2022

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
Copy link
Contributor

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
Copy link

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

@rddyck
Copy link

rddyck commented Mar 28, 2024

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 pushed a commit that referenced this issue Jun 10, 2024
@pjmolina pjmolina mentioned this issue Jun 10, 2024
@pjmolina
Copy link
Contributor

pjmolina commented Jun 10, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants