-
-
Notifications
You must be signed in to change notification settings - Fork 85
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
How about to use the "examples" function of Swagger? for convenience to front-end developer? #820
Comments
It is possible to support swagger examples. By the way, do you think that the examples should be put into the SDK? |
What you mean is to put true or false option of the 'examples' in I can't imagine how will you put the "examples" in SDK. |
/**
* Store an article.
*
* @param input Content to store
* @returns Newly archived article
* @deprecated
*
* @controller BbsArticlesController.store
* @path POST /bbs/articles
* @nestia Generated by Nestia - https://github.com/samchon/nestia
*/
export async function store(
connection: IConnection,
input: store.Input,
): Promise<store.Output> {
return PlainFetcher.fetch(
{
...connection,
headers: {
...connection.headers,
"Content-Type": "application/json",
},
},
{
...store.METADATA,
path: store.path(),
},
input,
);
}
export namespace store {
export type Input = Primitive<IBbsArticle.IStore>;
export type Output = Primitive<IBbsArticle>;
export const METADATA = {
method: "POST",
path: "/bbs/articles",
request: {
type: "application/json",
encrypted: false,
},
response: {
type: "application/json",
encrypted: false,
},
status: null,
} as const;
export const path = () => "/bbs/articles";
export const EXAMPLES: Output[] = [...];
} Something like this. |
oh, it looks great. If this function is released, I want to try it. I think that feels me comfortable. and this might be off topic... how about to add generic type of |
I will check the propagate type again. By the way, how to write the example data in the method? Do you have any idea? |
I think the "Example" of sdk should utilize as type rather than value. because It's so hard to use only type of result, and the input of "Example" is originally type. // api/typical/bbs/article
export namespace store {
export type Example<T> = T extends 404
? {code: 404, message: "no articles here"} | {code: 404, message: "no bbs here"}
: T extends 400
? ...etc : ...etc
}
// front
type ResponseError<T> = api.typical.bbs.article.store.Example<T>
try {
const res = await api.functional.bbs.article.store(url)
...
} catch (err) {
const errorData: ResponseError<typeof err.statusCode>;
...
} |
I always feel thank for you to make this great library.
This function that I will suggest from now is not necessary function. but It makes that the better User Experience.
currently, if we want to use two responses from same status code, the swagger makes the two responses belong to only "oneOf" option.
but, If you make that responses belong to also "examples" option, the user (especially front-end developer) can see the responses clearly as follow.
The text was updated successfully, but these errors were encountered: