Swagger / OpenAPI integration about rapidoid

[cnuonline]

This is must for making using for Restful documentation and lamba services need quick documentation

[picaron]

Hi @nmihajlovski

This would be a really cool feature to add

I imagine you are really busy.

I would be open to contribute this PR following your guidelines/suggestions on how to tackle this.

[nmihajlovski]

Hi @picaron, that sounds great! Thanks for taking initiative on this.

For easy illustration of the requirements, let's start with the following example:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: An paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

(source: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml)

For the info and servers sections we could introduce a new configuration section openapi.

Of course, the paths section will be more challenging. The paths can be automatically generated from the routes, but some information is missing: summary, description, tags, operationId, parameters (partially) etc.

As a first step I propose a simple bootstrap of OpenAPI from the information already available in the routes (e.g. generating basic paths from Rapidoid's routes (the parameters and responses will be missing, until we find a proper way of modelling them). Some suggestions:

• the OpenAPI / Swagger integration should ideally be implemented in a separate module rapidoid-openapi, similar to how it's done for the OAuth support,
• for the bootstrap: App.bootstrap(args).openapi(),
• basic configuration: openapi section (with corresponding Conf.OPENAPI) - useful for the info and servers elements of the spec.

I will try to find a proper way to model the parameters and responses...

Any feedback, questions and suggestions are welcome! :) Thanks again for helping with this one!

[ddorian]

Any (fastest) library that does something like https://marshmallow.readthedocs.io and can be connected to both swagger/rapidoid/routes so it validates request/response and also builds the api-specification. Like you can integrate python(flask+marshmallow+webargs+swagger+apispec).

In this case I think only the routes would be from rapidoid and the other stuff from external modules (no need to reinvent request parsing + validation?).

Make sense ?

[danielbraga]

Hi @nmihajlovski,

How to get paths, methods and parameters?

Thanks

[nmihajlovski]

@danielbraga Thanks for the PR! I merged it into a new branch: openapi.

The routes can be accessed using On.setup().routes().allNonAdmin().

The tricky part would be accessing the parameters. I am going to add support for a generic (JSON-style) "schema" property that can be configured per route.

[nmihajlovski]

@danielbraga @picaron FYI:

• I added meta-data model for the routes (RouteMeta),
• I removed the template-based YAML generation (@danielbraga sorry for that). Instead, I implemented dynamic docs construction from RouteMeta into Java collections, which are then rendered as JSON or YAML.

Also, I merged the openapi branch into master. This is still work in progress, but the next release of Rapidoid will have early-access/experimental OpenAPI support.

Open issues:

• smart construction of request/response data schema from Java types,
• support for response headers.

[nestoru]

Any possibility to actually make swagger the route definition holder? A DRY top down approach would ideally declare all of the below in swagger and only in swagger:

1. Route definitions with references to endpoint executable code
2. Validation of request payload against defined schema
3. Validation of response payload [optional for those that favor response time over spec-conformity]