server.reactive.session.cookie properties are not documented

[wilkinsona]

Hi, this is a first-timers-only issue. This means we've worked to make it more understandable to people who haven't contributed to our codebase before and are just getting started with making open source contributions in general.

If that's you, we're interested in helping you take the first step and can answer questions and help you out as you do. Those questions can be about the code, working with Git and GitHub – anything that you need some help with to make the contribution. Note that we're especially interested in contributions from people from groups underrepresented in free and open source software!

If you have had a pull request merged before, consider leaving this one for someone new, and looking through our general ideal-for-contribution issues. Thanks!

Problem

@DidierLoiseau has pointed out that the server.reactive.session.cookie properties are not documented. This means that they aren't listed in the reference documentation or in the metadata that enables auto-completion in an IDE when editing application.properties and application.yaml files.

The entries in the reference documentation are generated from the metadata so it's the metadata that needs to be corrected. It is generated using an annotation processor. The properties are defined on a Cookie class, an instance of which is used by ServerProperties.Reactive.Session:

spring-boot/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/ServerProperties.java

Line 326 in a4bafa8

private final Cookie cookie = new Cookie();

The annotation processor doesn't know that Cookie contains nested configuration properties so no metadata is generated.

Solution

org.springframework.boot.autoconfigure.web.ServerProperties.Reactive.Session should be updated to add @NestedConfigurationProperties to its cookie field. The source for this class is in ServerProperties.java that can be found at spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/web/ServerProperties.java in your git clone of the codebase.

The reference documentation can then be built (./gradlew spring-boot-project:spring-boot-docs:asciidoctor) to check that the property is now documented. The built documentation can be found beneath spring-boot-project/spring-boot-docs/build/docs/.

Steps to Fix

• Claim this issue with a comment below and ask any clarifying questions you need
• Set up a repository locally following the Contributing Guidelines
• Try to fix the issue following the steps above
• Commit your changes and start a pull request.

[hezean]

Hi, can you give me a chance to work on it? Many thanks!

[wilkinsona]

Thanks very much for the offer, @hezean. Looking at your GitHub profile, you appear to be an experienced contributor already. If you don't mind, we'd prefer that someone who's just getting started in open source has an opportunity to claim the issue.

[hezean]

Never mind, I'll look for other issues and try to start contributing to spring boot :)

[Adyel]

Hello @wilkinsona 👋,

Do you think I am eligible for this first-timers-only Issue? I would love to be involved in Spring development and this seems like a easy and approachable issue to start with.

[wilkinsona]

Thanks very much for the offer, @Adyel. We believe that fixing this issue will require a small change to a single class so it's not ideal for learning about Spring development. It's more suited to someone who wants to gain some experience of using GitHub and the pull request process. With 60 contributions in the last year, you appear to already be quite experienced in that area. If you don't mind, we'd prefer that it's claimed by someone who's really just getting started.

Please look out for issues labeled as ideal for contribution (we don't have any at the moment unfortunately) that are a better fit for someone who's contributed to OSS before but perhaps not to Spring.

[zantoichi]

Hello @wilkinsona

I think I can tackle this if you want me to try!

[wilkinsona]

Thanks for the offer, @zantoichi. I can see that you've already had a pull request merged. If you don't mind, we'd really like to invest our time in helping someone who hasn't been through the pull request process before.

Please look out for issues labeled as ideal for contribution (we don't have any at the moment unfortunately) that are a better fit for someone who's contributed to OSS before but perhaps not to Spring.

[Kalpesh-18]

Hey @wilkinsona am I eligible to work on it?

[wilkinsona]

@Kalpesh-18 It doesn't look like you've opened a pull request before, so yes you are. Thanks very much. I'll assign the issue to you. If you have any questions at all, please don't hesitate to ask.

[rajseth88]

Even I am not well versed with raising PR and cloning such large project repo in my local,could you please also assign me some task?

[Kalpesh-18]

Thank you @wilkinsona will work on it

[wilkinsona]

@rajseth88 Thanks for the offer. We don't have anything suitable right now, but please keep a look out for first-timers-only issues in the future.

[Kalpesh-18]

Hey @wilkinsona while importing it as a gradle project, should I import the entire spring-boot or just spring-boot-autoconfigure

[wilkinsona]

I would import everything by pointing your IDE at the root of your local git clone of the code.

[DidierLoiseau]

Thanks a lot for the reactivity!

In addition to the properties themselves, I think it would be useful to have a mention of those properties in the documentation itself to make it more easily discoverable. Section 8.5 Spring Session already mentions server.servlet.session.timeout but not the cookie properties, nor the equivalent reactive properties. Section 1.3.4. Customizing Embedded Servlet Containers mentions the cookie properties (and has a dedicated subsection specifically for the same-site property) but of course it only applies to servlet containers (might be worth linking the 2 sections though).

Also note that even for the servlet cookie properties, the JavaDoc is not copied into the generated documentation.

[wilkinsona]

As this is a first-timers-only issue, we want to keep the scope quite narrow. If further changes are necessary, we'll open another issue to tackle those. Thanks for the suggestions.

[wilkinsona]

Closing in favor of #31912.

[wilkinsona]

I've opened #31916 for the missing descriptions in the appendix. It's more than just the cookie properties that are affected. I've also opened #31917 to add some docs about the properties that are available to customize embedded reactive servers.