Swagger Improvement

[dmpvost]

First, congratulation for ActionHero! I think it's really great!

It's what I was trying to do with 2 projects myself, and the modularity is the most difficult part. I love the plugin idea!

Swagger improvement

I saw that ActionHero generate a Swagger documentation, that is great! 👍
It could be nice if it's go deeper

Currently, there is no swagger.yaml generate, could de in /dist ?
Why? swagger.yaml could be use with all swagger generator available, so it's easier to start a front app when all API is generate. (it's how we work on my company)
In the documentation, right now, there are no definition, so impossible to generate object from documentation.

It could be nice to have a fully documentation ready for generator.

ActionToSwagger

It could be nice if we could add some swagger decoration about input / output

Something like this maybe?

import {Action} from "actionhero";
import {ActionResponse} from "actionhero/dist/classes/action";

import {ApiMessage} from "@/models/apiMessage";
import {ApiError} from "@/models/apiError";

import {Response} from 'typescript-rest-swagger';
import {Param, PathParam} from "typescript-rest";


export class ChatsList extends Action {

    constructor() {
        super();
        this.name = "chats_list";
        this.description = "Get all my history chat";
        this.outputExample = {};
        this.inputs = {
            cust_uuid: {
                required: true,
            },
            order: {
                required: false,
            },
        };
    }

    @Response<ApiMessage>(200, 'Retrieve a list of people.')
    @Response<ApiError>(401, 'The user is unauthorized.')
    @PathParam('cust_uuid')
    //@Param<ApiMessage>('body')

    async run({params}: { params: { cust_uuid: string } }): Promise<ActionResponse> {
        // your logic here
        console.log("params:", params);
        return {cust_uuid: params.cust_uuid};
    }
}

It's just the idea, but if we are able description input/output with object, it open a lot of possibility to be compatible with a lot of things.
Goal: have a full documentation OpenApi 2.0 (for start)

SwaggerToAction

I saw that the CLI could create a new action!

We could parse swagger.yaml of any existing project, that will help for migration to ActionHero, and generate all action and route by the way from documentation

Of course it's only a squelette, but it help to start with something.

And finally, after running ActionToSwagger, we could find back our documentation in dist/swagger.yaml

Why?

By exemple, I have few project using swagger as a core feature.
So I have multiple projet documented, with 14k lignes of swagger ready to be used.

As swagger documentation become more and more popular it could be a great feature

How to do that?

1. ActionToSwagger

how combine, input, object definition, swagger definition, with decorator? with something else?
There is typescript-rest and typescript-rest-swagger as beginning

And after just generate the documentation

2. SwaggerToAction

Parsing the documentation is not so difficult, and use the existing CLI with more option as parameters?

For object, swagger-codegen generate them well with angular option. I use the model generate currently on all my project.

But maybe it's better to generator our ActionModel from documentation, so it could generate object inside the projet with Input in the same way?
I mean Input of an Action

3. Where

Last question: what is the right place for this feature? As a plugin? As a core feature? As an NPM module?

[evantahler]

Welcome @dmpvost!

These are all awesome ideas!

Right now, all of Actionhero's swagger tooling lives in user-space, within the swagger action. We do this because there are so many nuances you may want to customize with the "translating" between how Actionhero works and what the swagger spec wants. There are a lot of assumptions made that we want to let people customize.

Keeping the above in mind, I think the quickest way to build the swagger.yml file would be add a CLI command into Actionhero that takes the output of the swagger action and writes the YML file. That should be pretty straight-forward once #1628 is merged in. The interface could be actionhero swagger export --file='/path/to/swagger.yml'. I would suggest that this be included in the core of Actionhero, along with our other CLI methods.

For your other suggestions, I'd be a little wary of adding Swagger decoration/tooling as a primitive to all Actionhero Actions. We try to keep actions generic for all of the transports Actionhero can provide, and Swagger really only works for HTTP, not websocket, TCP socket, etc. BUT, you could certainly add that as part of a plugin! Rather than extending Action you could extend SwaggerAction which is provided by your plugin. In this case, you could assume that your SwaggerActions only work of HTTP clients and you could generically handle the response codes and such.

Also, I personally don't use Swagger and rely more on Typescript to keep my font and back-ends in sync (https://www.grouparoo.com/blog/typescript-frontend-backend)... so I'm probably not the best person to ask what a modern Swagger project looks like 😄

[dmpvost]

Thank for your reply,

I will play more with ActionHero as primitive, and I will think about a plugin with swagger. Is it a plugin or just a NPM package?
A plugin is only useful if it provide action/task/middleware/intialization? Otherwise it's just a simple NPM package build for ActionHero? I'm thinking what is the best option for that

Typescript is enough when you have only "web" project, but if you have to do multi platform like IOS switch, or Android native etc... it's more complicated. An other advantage is that, If want that your API will be integrate by other, it's easy to build a client API for every language.

[evantahler]

Oh! Plugins are like mini Actionhero projects - https://www.actionherojs.com/tutorials/plugins
They can be either local or distributed on NPM

[dmpvost]

I found this documentation project for socket - asyncapi

As swagger can only document rest-api, we could generate 2 documentations for both case.
In this case, it start to be interesting to describe input/output