Optional path variables are marked as required

Hello,

It seems that the required parameter of the @PathVariable annotation is not being respected. The generated spec always marks the parameter as being required.

To Reproduce The following class demonstrates the issue. This is from a stock Spring Boot project, with only the Web starter and Springdoc as dependencies:

package com.cyberscout.springdocbug;


import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.Map;

import static org.springframework.web.bind.annotation.RequestMethod.GET;


@RestController
@RequestMapping("/test")
public class TestController {

    @RequestMapping(path = "/{param}", method = GET)
    public Map<String, String> doIt(@PathVariable(name = "param", required = false) String param) {

        Map<String, String> result = new HashMap<>();
        if (param != null) {
            result.put("param", param);
            result.put("empty", "false");
        }
        else {
            result.put("empty", "true");
        }
        return result;
    }
}

This is a snippet of the spec that is generated:

paths:
  /test/{param}:
    get:
      # ...
      parameters:
      - name: param
        in: path
        required: true
        schema:
          type: string

Expected behavior The path parameter should be marked as optional in the generated spec.

[macdaddyaz]

You workaround is better, and adds more clarity to what you want achieve.

I respectfully disagree. As I said, taking a single method that works perfectly fine, and splitting it into two in order to appease my documentation tool is artificial. There is nothing else about the structure or logic of the code that calls for two methods there. A simple null-check (if it’s even needed) is far more clear than multiple methods that are nearly-identical in signature, annotations, and behavior.

There is no magic for documentation generation.

Well, I’m not expecting magic. 😄 But stylistic debates aside, I still believe there is a bug here. I don’t know the ins and outs of the OAS the way you do, but I’m fairly certain that the snippet of YAML I pasted above is not compliant with the specification of the name field:

If in is “path”, the name field MUST correspond to a template expression occurring within the path field in the Paths Object. See Path Templating for further information.

[bnasslahsen]

You can have a look at the follwing class/method if more interested: io.swagger.v3.oas.models.parameters.Parameter.setIn, from the swagger-models.

    public void setIn(String in) {
        if ("path".equals(in)) {
            this.required = true;
        }

        this.in = in;
    }

The library springdoc-openapi is built on the top of swagger-api and swagger-ui, which represents the main OpenAPI 3 implementation. There are certainly, some features permitted by spring, that may not be compliant with the OpenAPI specification. Having the possibility of path parameters to be false, is one of them. But not the only one.

As mentioned before, you can choose to make your code simpler, which will help you get the best of both worlds (spring and OpenAPI). The choice is up to you…