OpenAPI docs source

[renatolond]

On the Rodauth docs, there's a link to the OpenAPI docs in postman. Since I'll be making my API available for external consumers, I'd like to add those methods to it too. I was wondering if this is auto-generated (so I could generate it along my API) or if not, if it's published along with new releases (so I have to add it manually to my docs when upgrading rodauth).

[jeremyevans]

This link isn't autogenerated. It also isn't anywhere near complete. It was submitted by a user in #374, and looked useful, so I merged it. However, it is not official Rodauth documentation, and I cannot vouch for anything that page.

[janko]

FYI, I'm working on a gem that will generate OpenAPI docs from the given Rodauth configuration. Last night I managed to come up with a DSL that will make it maintainable. I have some basic features already implemented, there are still a lot more to go.

Here is the WIP in case you're interested – https://gist.github.com/janko/34450a52ac9afc1df7cb0b23ee9ab64f 🙂 It currently generates the following YAML:

Open API docs

openapi: 3.0.1
info:
  title: Rodauth
  description: This lists all the endpoints provided by Rodauth features.
  version: 2.36.0
externalDocs:
  description: Rodauth documentation
  url: https://rodauth.jeremyevans.net/documentation.html
tags:
- name: Login
  externalDocs:
    description: API docs
    url: http://rodauth.jeremyevans.net/rdoc/files/doc/login_rdoc.html
- name: Logout
  externalDocs:
    description: API docs
    url: http://rodauth.jeremyevans.net/rdoc/files/doc/logout_rdoc.html
- name: Create Account
  externalDocs:
    description: API docs
    url: http://rodauth.jeremyevans.net/rdoc/files/doc/create_account_rdoc.html
- name: Verify Account
  externalDocs:
    description: API docs
    url: http://rodauth.jeremyevans.net/rdoc/files/doc/verify_account_rdoc.html
- name: Change Password
  externalDocs:
    description: API docs
    url: http://rodauth.jeremyevans.net/rdoc/files/doc/change_password_rdoc.html
paths:
  "/login":
    get:
      tags:
      - Login
      summary: View Login page
      responses:
        '200':
          description: Rendered login page
      parameters: []
    post:
      tags:
      - Login
      summary: Perform login
      responses:
        '302':
          description: successful login
        '401':
          description: no matching login, invalid password
        '403':
          description: unverified account
      parameters:
      - name: login
        in: query
        description: Email address for the account
        required: true
        style: form
        example: [email protected]
        schema:
          type: string
      - name: password
        in: query
        description: Password for the account
        required: true
        style: form
        example: secret123
        schema:
          type: string
  "/logout":
    get:
      tags:
      - Logout
      summary: View logout page
      responses:
        '200':
          description: Rendered logout page
      parameters: []
    post:
      tags:
      - Logout
      summary: Perform logout
      responses:
        '302':
          description: successful logout
      parameters: []
  "/create-account":
    get:
      tags:
      - Create Account
      summary: View registration page
      responses:
        '200':
          description: Rendered registration page
      parameters: []
    post:
      tags:
      - Create Account
      summary: Perform registration
      responses:
        '302':
          description: successful registration
        '422':
          description: invalid login
      parameters:
      - name: login
        in: query
        description: Email address for the account
        required: true
        style: form
        example: [email protected]
        schema:
          type: string
  "/verify-account":
    get:
      tags:
      - Verify Account
      summary: View email verification page
      responses:
        '200':
          description: Rendered verification page
        '302':
          description: invalid verify account key
      parameters:
      - name: key
        in: query
        description: Email verification key
        required: false
        style: form
        example: "<account_id>_<key_hmac>"
        schema:
          type: string
    post:
      tags:
      - Verify Account
      summary: Perform email verification
      responses:
        '302':
          description: successful email verification, Missing or invalid token
        '422':
          description: invalid password, passwords do not match
      parameters:
      - name: key
        in: query
        description: Email verification token
        required: false
        style: form
        example: "<account_id>_<key_hmac>"
        schema:
          type: string
      - name: password
        in: query
        description: Password to set
        required: true
        style: form
        example: secret123
        schema:
          type: string
      - name: password-confirm
        in: query
        description: Password confirmation
        required: true
        style: form
        example: secret123
        schema:
          type: string
  "/verify-account-resend":
    get:
      tags:
      - Verify Account
      summary: Resend account verification email page
      responses:
        '200':
          description: Rendered resend account verification page
      parameters: []
    post:
      tags:
      - Verify Account
      summary: Perform resending account verification email
      responses:
        '302':
          description: successful resend, email recently sent
        '401':
          description: no matching login
      parameters:
      - name: login
        in: query
        description: Email address for the account
        required: true
        style: form
        example: [email protected]
        schema:
          type: string
  "/change-password":
    get:
      tags:
      - Change Password
      summary: View change password page
      responses:
        '200':
          description: Rendered change password page
        '302':
          description: Login required
      parameters: []
    post:
      tags:
      - Change Password
      summary: Perform password change
      responses:
        '302':
          description: successful password change
        '401':
          description: invalid previous password
        '422':
          description: same as existing password, invalid password, passwords do not
            match
      parameters:
      - name: password
        in: query
        description: Current account password
        required: true
        style: form
        example: oldsecret123
        schema:
          type: string
      - name: new-password
        in: query
        description: Password to set
        required: true
        style: form
        example: newsecret123
        schema:
          type: string
      - name: password-confirm
        in: query
        description: Password confirmation
        required: true
        style: form
        example: newsecret123
        schema:
          type: string

[jeremyevans]

@janko That looks interesting. How important do you think it is to have OpenAPI docs for Rodauth? Is it something you think we should include by default and all features should support? I'd be hesitant to do that, but I'm open to your suggestions.

[janko]

I think it's important for people understanding Rodauth endpoints and parameters they accept, especially for those using the JSON API, since the default endpoints aren't documented anywhere.

Since every Rodauth configuration is different – different features can be enabled, route paths can be changed, different parameters can be accepted/required – I think it's best if people generated the OpenAPI docs themselves dynamically for their own configuration.

[janko]

The idea is to just copy-paste the OpenAPI YAML result into something like editor.swagger.io and browse the endpoints.

[jeremyevans]

I will defer to your more extensive experience in this area. If you think this is something that Rodauth should ship with, please submit a pull request when you are ready. Thanks!

[janko]

I just released it as a gem – https://github.com/janko/rodauth-openapi 🙂

Since I consider this tooling, in the sense that it doesn't modify Rodauth behavior, it made more sense to me as an external gem. I will submit a PR to add it to the Rodauth website.

[HoneyryderChuck]

A bit late to the discussion, but I think that the lack of input validation, particularly in the JSON api mode, is a gap worth filling. If rodauth routes could provide a way to declare which params a feature expects, which are required, which type, etc... it'd be possible to build a JSON schema contract, which corresponding tools could use to validate prior to route block evaluation.

Openapi docs are neat, but I always find them a bit suboptimal as implementation tends to drift from it. I don't think the latter is such a big issue for the level of API stability rodauth provides, but until someone runs actual request/response payloads through them, we can't be sure they're accurate.

Another point particularly for @janko 's openapi docs plugin is that it's built for "stock" rodauth, but I don't see a straightforward way for another plugin with routes (such as rodauth-oauth) to use it.

[janko]

@HoneyryderChuck How would you handle params that are required in GET endpoint put optional in POST endpoint (e.g. token params)? Or, much more common, params that are only for GET or only for POST endpoint.

Not sure exactly what is the motivation behind building this into Rodauth. Params will very rarely change, so there is low chance of rodauth-openapi becoming outdated.

[HoneyryderChuck]

How would you handle params that are required in GET endpoint put optional in POST endpoint (e.g. token params)?

Not sure what you mean by token params 🤔 I can only find references to token params in the context of email based features, which I'd consider out of scope. As for the rest, I'm not considering GET endpoints, as there are no params to consider there (in the context of API usage, which also discards GET endpoints already).

Not sure exactly what is the motivation behind building this into Rodauth. Params will very rarely change

You are right (I did mention that in my top comment). The main motivation, in the context of JSON usage mode, would be to fail with a specific status code. / error message (422 / "invalid param" / "required param") when i.e. the "password" value is an integer, or some mandatory param isn't there, and the business logic does not need to be invoked in such cases. It's something I'd consider a massive win for rodauth-oauth, which has to support RFC-mandated contracts which surpass the complexity of most request params supported by stock rodauth features.

It'd also (arguably) improve integration of rodauth in API-based services which may want to standardize the contract negotiation across the whole application and not have to maintain a separate way of doing it only for the rodauth-based authentication layer. I'm assuming a wider footprint for JSON schema based validation as the standardized method of doing things, but it's by no means the only one (there could be protobuf contracts, or something more ruby-specific like dry-validation contracts), which could make a lighter specification flexible enough (rodauth kind of supports this already for translations, where the translatable_method exists, and the i18n feature uses it).

[janko]

Not sure what you mean by token params 🤔

Yeah, as you guessed, I was referring to email link tokens for reset_password, verify_account, verify_login_change, email_auth/ etc.

I can only find references to token params in the context of email based features, which I'd consider out of scope.

You mean out of scope for GET endpoints? Because they're required for POST endpoints in JSON mode.

As for the rest, I'm not considering GET endpoints, as there are no params to consider there (in the context of API usage, which also discards GET endpoints already).

Getting an overview of endpoint params is useful for HTML mode as well. Other than helping in learning how Rodauth works, it's also useful when writing request specs for Rodauth endpoints, where you need to know names of params.

The main motivation, in the context of JSON usage mode, would be to fail with a specific status code. / error message (422 / "invalid param" / "required param") when i.e. the "password" value is an integer, or some mandatory param isn't there, and the business logic does not need to be invoked in such cases.

Having an explicit "this param is required" validation error does sound useful in JSON API context. E.g. instead of getting a "password do not match" error on password field, it would be clearer to get a "required param" error on password-confirm field. I'm seeing an opportunity for a param! method that does nothing in HTML mode but in JSON mode returns a missing param error.

I'm not seeing much potential from type checking here (at least for built-in params), because in HTML mode it's all strings anyway, and JSON mode inherits that. There are some boolean fields, but Rodauth just checks presence as truthiness.

It's something I'd consider a massive win for rodauth-oauth, which has to support RFC-mandated contracts which surpass the complexity of most request params supported by stock rodauth features.

Did you mean for the gem itself or for apps using rodauth-oauth? What would explicit JSON schema contracts for rodauth-oauth params provide that OpenAPI documentation (which declares params using JSON schemas) wouldn't?

It'd also (arguably) improve integration of rodauth in API-based services which may want to standardize the contract negotiation across the whole application and not have to maintain a separate way of doing it only for the rodauth-based authentication layer.

In this example, API-based applications that use Rodauth could extract JSON schemas for params from the OpenAPI documentation, right? I admit I don't have any experience with JSON schema contracts.

[janko]

To be clear, I'm not trying to defend rodauth-openapi as a solution for all purposes. I'm just trying to understand what specific use cases it cannot support, because I would like it if Rodauth didn't have to duplicate the work already done in rodauth-openapi.

[HoneyryderChuck]

You mean out of scope for GET endpoints? Because they're required for POST endpoints in JSON mode.

rodauth in JSON mode rejects requests other than POST with a 405 status code.

Getting an overview of endpoint params is useful for HTML mode as well. Other than helping in learning how Rodauth works, ...

Definitely not questioning its value for documentation, I was focusing on the "schema validation" angle. From that perspective, they have less (no?) value.

I'm seeing an opportunity for a param! method that does nothing in HTML mode but in JSON mode returns a missing param error.

Indeed, that's the gist of the proposal for stock rodauth. Still, not really sold on whether stock rodauth should do anything with it, rather than leave that decision to external features (a bit like it's done with translatable_method), but that's a debatable topic.

I'm not seeing much potential from type checking here (at least for built-in params), because in HTML mode it's all strings anyway, and JSON mode inherits that.

Not targeting type-checking itself, just payload schema validation (and eventually type coercion). Regarding "HTML is all strings", and assuming you mean "x-www-form-urlencoded" format, that's again something where such a layer helps more than hinders (and there's even a roda plugin dedicated to help with that problem.

Did you mean for the gem itself or for apps using rodauth-oauth? What would explicit JSON schema contracts for rodauth-oauth params provide that OpenAPI documentation (which declares params using JSON schemas) wouldn't?

In rodauth-oauth, there's a subset of validate_* functions only dedicated to the problem of enforcing the RFC contracts, which have to be done this way due to the lack of a "request payload validation" capability on stock rodauth. This is definitely in my "features I wish rodauth had" top 3 :)

As mentioned above, OpenAPI documentation does not, by itself, ATM, eliminate the need of me to write custom code to validate/enforce contracts myself. It also, by proxy, does not prevent documentation-to-implementation drift (which I agreed above has les value in the case of rodauth relatively stable contracts). It's value is solely for documentation on how to use it.

In this example, API-based applications that use Rodauth could extract JSON schemas for params from the OpenAPI documentation, right?

Extracting, perhaps (with the help of some tooling). They wouldn't be able to enforce it though, without using one of the available rodauth pre-route eval callbacks, or monkeypatching the library (I'm not sure if the former is possible).