Getting Started

This guide will walk you through the first steps of using Thymian. Let’s get started right away!

Prerequisites

• You need any of the following Node.js LTS versions: 20, 22, or 24
• Any Swagger/OpenAPI specification file (OpenAPI version 3.2 is currently not supported)

Installation

You won’t need to install Thymian locally, we will just use npx for this.

Check if you can run Thymian by running the following command:

npx thymian --version

First Run Without a Config

Now navigate to your project’s root directory and run Thymian directly against your API description:

npx thymian lint --spec openapi:openapi.yaml

This is the fastest onboarding path. It lets you validate one API immediately without creating a configuration file first.

If you want to keep that setup for future runs, generate a reusable config afterward:

npx thymian generate config

This command will:

1. Detect your OpenAPI specification file
2. Let you choose which file to use when multiple specs are found
3. Create a thymian.config.yaml configuration file in your project

Understanding the Configuration File

After running generate config, you’ll have a thymian.config.yaml file that looks like this:

# Thymian Configuration
# Generated by `thymian generate config`

specifications:
  - type: openapi
    location: ./path/to/your/openapi.yaml

ruleSets:
  - '@thymian/rules-rfc-9110'

ruleSeverity: error # will only show errors

plugins:
  '@thymian/plugin-openapi': {}
  '@thymian/plugin-http-linter': {}
  '@thymian/plugin-request-dispatcher': {}
  '@thymian/plugin-sampler': {}
  '@thymian/plugin-reporter':
    options:
      formatters:
        text: {}
  '@thymian/plugin-http-tester': {}
  '@thymian/plugin-http-analyzer': {}

Key sections:

• specifications: Lists your API specification files. Each entry has a type (e.g., openapi) and location (path to the file).
• ruleSets: Which rule sets to apply. The default is @thymian/rules-rfc-9110 for HTTP conformance rules.
• ruleSeverity: The minimum severity level to report (error, warn, or hint).
• plugins: The Thymian plugins to load. Plugins handle parsing, validation, reporting, and more.

Tip

You can list your loaded plugins via:

npx thymian plugins list

Running With a Saved Configuration

After generating a config file, run your next analysis from your project’s root directory:

npx thymian lint

This command will:

1. Load your OpenAPI specification

   Loads your OpenAPI specification(s) and transforms them into a single, unified model (the Thymian format).

2. Load HTTP Rules

   Loads all rule sets specified in the configuration file under ruleSets. In the example of this guide, we’re using the rule set extracted from RFC 9110.

3. Static analysis

   Applies all loaded rules to your OpenAPI specification. Each rule checks for specific HTTP conformance issues and generates results based on the findings.

4. Display results

   Displays all found issues in the terminal.

Understanding the Results

Thymian will output results in a structured format. Here is an exemplary output from the HTTP linter:

@thymian/plugin-http-linter ─────────────────────────────────────────────────────

  34 HTTP rules run successfully. 2 rules reported a violation.


     PUT /launches/{id} - application/json → 401 UNAUTHORIZED

        ✖ error: The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
           rfc9110/server-must-send-www-authenticate-header-for-401-response

    DELETE /launches/{id} → 401 UNAUTHORIZED

        ✖ error: The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
           rfc9110/server-must-send-www-authenticate-header-for-401-response


Found 2 errors, 0 warnings and 0 hints.

In this example, two problems were found in the OpenAPI specification. And since we configured the linter to only show errors, both of them are marked as such. Let’s take a closer look and analyze the first issue in detail.

Severity Level

PUT /launches/{id} - application/json → 401 UNAUTHORIZED
      ✖ error: The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
         rfc9110/server-must-send-www-authenticate-header-for-401-response

Each problem found is assigned a severity level based on the rule it was triggered by. In this case, the severity level is error. This indicates that the issue violates the HTTP specification and can cause issues with interoperability or performance, for example. Besides the error severity level, there are also warn and hint, indicating a potential conformance issue and a suggestion for a truly optional mechanism of HTTP, respectively.

Symbol	Severity	Description
✖	error	Problem that needs to be fixed.
⚠	warn	Problem that should be fixed. May be left as is under certain circumstances.
ℹ	hint	Only a suggestion.

When no problems are found, Thymian displays: ✓ No problems found.

Tip

You can override the minimum reported severity at the command line with the --rule-severity flag. For example, to also see warnings and hints:

npx thymian lint --rule-severity hint

This overrides the ruleSeverity value set in your configuration file.

Description

PUT /launches/{id} - application/json → 401 UNAUTHORIZED
      ✖ error: The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
         rfc9110/server-must-send-www-authenticate-header-for-401-response

After the severity level, the description of the problem is shown. This explains what the rule requires. This description is the way to understand the problem and how to fix it.

Location

PUT /launches/{id} - application/json → 401 UNAUTHORIZED
      ✖ error: The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
         rfc9110/server-must-send-www-authenticate-header-for-401-response

Next, we look at the exact location of the problem in the OpenAPI specification. As shown above, the problem is located in the 401 UNAUTHORIZED response for the PUT /launches/{id} operation. So to fix this issue, you would need to navigate to the corresponding operation in the Swagger/OpenAPI specification and add the missing WWW-Authenticate header to the 401 response definition. This could look like this:

'401':
  description: Unauthorized
  headers:
    WWW-Authenticate:
      schema:
        type: string

Source

PUT /launches/{id} - application/json → 401 UNAUTHORIZED
      ✖ error: The server generating a 401 response MUST send a WWW-Authenticate header field containing at least one challenge applicable to the target resource.
         rfc9110/server-must-send-www-authenticate-header-for-401-response

Finally, we look at the rule that triggered the problem. In this case, the rule is rfc9110/server-must-send-www-authenticate-header-for-401-response.

Summary

What did you just do? You have linted your OpenAPI specification and checked your API description for potential HTTP conformance issues. Based on your configured ruleSeverity Thymian shows you problems, that MUST, SHOULD or MAY be fixed. If you fixed all problems, you’re ready for your next steps with Thymian and to spice up your API 🌿!

Next Steps

To statically analyze your OpenAPI specification was just your first step. Thymian has much more to offer and can be your swiss army knife for your HTTP API development process.

Extending Thymian with Plugins

Don’t want to add yet another tool to your development process? Thymian’s plugin architecture lets you integrate tools you’re already using by integrating them as plugin.

It even provides the possibility to write plugins in any of your favorite languages or to connect remote plugins. For this use case, Thymian provides a proxy plugin. This allows you to connect your plugins via WebSockets. See this guide to learn how to develop such a plugin.