[WIP] Testing out what copilot could do if I asked it to document the code #202
Conversation
WalkthroughThe pull request introduces comprehensive API documentation support for a Spring Boot application via Springdoc/OpenAPI integration. It adds OpenAPI configuration, Swagger annotations to controllers, documentation properties, build dependencies, and four new Markdown documentation files along with a documentation map. Changes
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🧹 Nitpick comments (3)
src/main/java/org/kpmp/QueryController.java (1)
42-45: Consider adding method-level @operation annotations for comprehensive GraphQL documentation.While the class-level @tag annotation is good, individual GraphQL query methods lack @operation annotations that would provide detailed documentation for each query. This is inconsistent with the pattern used in ErrorController (line 31) and CacheController (line 24).
Consider adding @operation annotations to key GraphQL methods. Example:
+import io.swagger.v3.oas.annotations.Operation; + @Controller @Tag(name = "GraphQL Queries", description = "GraphQL queries for retrieving KPMP atlas data - accessible via POST /graphql") public class QueryController implements GraphQLQueryResolver { + @Operation(summary = "Search for genes, proteins, or cell types", + description = "Returns autocomplete suggestions based on the search term") @QueryMapping public List<AutocompleteResult> autocomplete(@Argument String searchTerm) throws IOException, Exception { return autocompleteService.query(searchTerm); }Note: Given the large number of methods (~30+), you may want to prioritize documenting the most frequently used queries first.
ENDPOINTS.md (1)
659-664: Consider improving cURL example readability.The GraphQL query at line 662 contains highly escaped JSON which is difficult to read. While technically correct, consider reformatting for clarity in documentation.
Instead of:
"query": "query { geneExpressionSummary(dataType: \"singleCell\", geneSymbol: \"APOL1\", cellType: \"\", enrollmentCategory: \"CKD\") { gene cellType mean } }"Consider using a file-based approach or formatting helper:
- curl -X POST http://localhost:8080/graphql \ - -H "Content-Type: application/json" \ - -d '{ - "query": "query { geneExpressionSummary(dataType: \"singleCell\", geneSymbol: \"APOL1\", cellType: \"\", enrollmentCategory: \"CKD\") { gene cellType mean } }" - }' + # Save query to file: query.graphql + # query { + # geneExpressionSummary( + # dataType: "singleCell" + # geneSymbol: "APOL1" + # cellType: "" + # enrollmentCategory: "CKD" + # ) { + # gene cellType mean + # } + # } + + curl -X POST http://localhost:8080/graphql \ + -H "Content-Type: application/json" \ + -d @- << 'EOF' + { + "query": "query { geneExpressionSummary(dataType: \"singleCell\", geneSymbol: \"APOL1\", cellType: \"\", enrollmentCategory: \"CKD\") { gene cellType mean } }" + } + EOFDEVELOPER_GUIDE.md (1)
58-62: Clearly mark authentication examples as placeholder values.Lines 58-62 and 66-70 show authentication header examples with "your-api-key" and "eyJhbGc..." placeholders. While these are obviously examples, clarify to users that they should never commit real tokens to version control or documentation.
Add a note above the authentication examples:
#### Option 1: API Key Authentication + + ⚠️ **IMPORTANT**: Never commit real API keys to version control or documentation. Use environment variables or secure secret management instead. + ```bash curl -X POST http://api.example.com/graphql \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{"query": "..."}'Option 2: JWT Bearer Token
⚠️ IMPORTANT: Never commit real tokens to version control or documentation. Use environment variables or secure secret management instead.Also applies to: 66-70 </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between b8630468d84403269233bb3c0243c6dfcabb1b3d and 9ed50639f4351e6bf88a273c34a3d0a27796ab51. </details> <details> <summary>📒 Files selected for processing (13)</summary> * `.classpath` (1 hunks) * `API_DOCUMENTATION_README.md` (1 hunks) * `API_QUICK_REFERENCE.md` (1 hunks) * `DEVELOPER_GUIDE.md` (1 hunks) * `DOCUMENTATION_IMPLEMENTATION.md` (1 hunks) * `DOCUMENTATION_MAP.txt` (1 hunks) * `ENDPOINTS.md` (1 hunks) * `build.gradle` (1 hunks) * `src/main/java/org/kpmp/OpenAPIConfiguration.java` (1 hunks) * `src/main/java/org/kpmp/QueryController.java` (1 hunks) * `src/main/java/org/kpmp/cache/CacheController.java` (1 hunks) * `src/main/java/org/kpmp/errors/ErrorController.java` (2 hunks) * `src/main/resources/application.properties` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧬 Code graph analysis (3)</summary> <details> <summary>src/main/java/org/kpmp/errors/ErrorController.java (2)</summary><blockquote> <details> <summary>src/main/java/org/kpmp/QueryController.java (1)</summary> * `Controller` (44-344) </details> <details> <summary>src/main/java/org/kpmp/cache/CacheController.java (1)</summary> * `Controller` (17-42) </details> </blockquote></details> <details> <summary>src/main/java/org/kpmp/cache/CacheController.java (1)</summary><blockquote> <details> <summary>src/main/java/org/kpmp/errors/ErrorController.java (1)</summary> * `Controller` (20-42) </details> </blockquote></details> <details> <summary>src/main/java/org/kpmp/QueryController.java (2)</summary><blockquote> <details> <summary>src/main/java/org/kpmp/cache/CacheController.java (1)</summary> * `Controller` (17-42) </details> <details> <summary>src/main/java/org/kpmp/errors/ErrorController.java (1)</summary> * `Controller` (20-42) </details> </blockquote></details> </details><details> <summary>🪛 Gitleaks (8.30.0)</summary> <details> <summary>DEVELOPER_GUIDE.md</summary> [high] 58-60: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource. (curl-auth-header) --- [high] 66-68: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource. (curl-auth-header) </details> </details> <details> <summary>🪛 LanguageTool</summary> <details> <summary>API_DOCUMENTATION_README.md</summary> [uncategorized] ~169-~169: If this is a compound adjective that modifies the following noun, use a hyphen. Context: ...ent API key or JWT authentication - Add rate limiting - Use HTTPS/TLS - Implement request val... (EN_COMPOUND_ADJECTIVE_INTERNAL) --- [style] ~242-~242: Some style guides suggest that commas should set off the year in a month-day-year date. Context: ... | --- **Last Updated:** December 17, 2025 **API Version:** 3.1.0 **Spring Boo... (MISSING_COMMA_AFTER_YEAR) </details> <details> <summary>DOCUMENTATION_MAP.txt</summary> [style] ~230-~230: Some style guides suggest that commas should set off the year in a month-day-year date. Context: ...━━━━━━━━━━━━ Last Updated: December 17, 2025 Documentation Version: 1.0 API Version:... (MISSING_COMMA_AFTER_YEAR) </details> <details> <summary>DOCUMENTATION_IMPLEMENTATION.md</summary> [style] ~122-~122: This phrasing can be overused. Try elevating your writing with a more formal alternative. Context: ...ification | ### 3. Choose Your Path **If you want...** - **Quick answers** → Read [API_QU... (IF_YOU_WANT) --- [style] ~289-~289: Some style guides suggest that commas should set off the year in a month-day-year date. Context: ... **Implementation Date:** December 17, 2025 **API Version:** 3.1.0 **Documentat... (MISSING_COMMA_AFTER_YEAR) </details> </details> <details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>API_DOCUMENTATION_README.md</summary> 41-41: Bare URL used (MD034, no-bare-urls) --- 42-42: Bare URL used (MD034, no-bare-urls) --- 43-43: Bare URL used (MD034, no-bare-urls) --- 187-187: Bare URL used (MD034, no-bare-urls) --- 188-188: Bare URL used (MD034, no-bare-urls) --- 189-189: Bare URL used (MD034, no-bare-urls) --- 190-190: Bare URL used (MD034, no-bare-urls) --- 230-230: Bare URL used (MD034, no-bare-urls) </details> <details> <summary>API_QUICK_REFERENCE.md</summary> 239-239: Bare URL used (MD034, no-bare-urls) </details> <details> <summary>DOCUMENTATION_IMPLEMENTATION.md</summary> 116-116: Bare URL used (MD034, no-bare-urls) --- 117-117: Bare URL used (MD034, no-bare-urls) --- 118-118: Bare URL used (MD034, no-bare-urls) </details> <details> <summary>DEVELOPER_GUIDE.md</summary> 541-541: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 550-550: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 562-562: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 579-579: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 590-590: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 600-600: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (10)</summary><blockquote> <details> <summary>.classpath (1)</summary><blockquote> `1-25`: The `.classpath` file appears correctly configured for this Gradle-based project with proper source path separation (test/main), Gradle scope attributes, and JavaSE-21 JRE container. > Likely an incorrect or invalid review comment. </blockquote></details> <details> <summary>src/main/java/org/kpmp/errors/ErrorController.java (1)</summary><blockquote> `14-32`: **LGTM! Well-structured OpenAPI documentation.** The OpenAPI annotations are properly applied with clear descriptions. The @ApiResponse correctly documents the Boolean return type and 200 response code. </blockquote></details> <details> <summary>src/main/java/org/kpmp/OpenAPIConfiguration.java (1)</summary><blockquote> `31-59`: **Excellent comprehensive API description!** The detailed description in the OpenAPI info section provides clear documentation of key features, quick start examples, and access points. This will greatly improve the developer experience. </blockquote></details> <details> <summary>src/main/java/org/kpmp/cache/CacheController.java (1)</summary><blockquote> `9-25`: **LGTM! Comprehensive OpenAPI documentation for cache management.** The OpenAPI annotations are well-structured with clear descriptions. The @Tag groups the cache management functionality appropriately, and the @Operation/@ApiResponse provide detailed documentation for the clearCache endpoint. </blockquote></details> <details> <summary>DOCUMENTATION_IMPLEMENTATION.md (2)</summary><blockquote> `1-41`: **Excellent comprehensive implementation documentation!** This documentation provides a clear overview of what was added, organized by file type with helpful read time estimates. The structure makes it easy for team members to understand the scope of changes and navigate to relevant resources. --- `196-203`: **Helpful maintenance checklist for future updates.** The documentation update checklist provides clear guidance for maintaining the API documentation alongside code changes. This will help ensure documentation stays synchronized with the API. </blockquote></details> <details> <summary>API_QUICK_REFERENCE.md (1)</summary><blockquote> `1-239`: **Overall documentation structure is clear and well-organized.** The quick reference file effectively provides a fast lookup for common API tasks with good examples in multiple languages (cURL, Python, JavaScript). The tables are informative and the troubleshooting section is practical. The file complements the other documentation files well. </blockquote></details> <details> <summary>ENDPOINTS.md (1)</summary><blockquote> `703-706`: **Version information in ENDPOINTS.md is accurate.** All documented versions match the actual project configuration: version 3.1.0 in build.gradle, Spring Boot 3.2.5, and Java 21 sourceCompatibility/targetCompatibility. </blockquote></details> <details> <summary>API_DOCUMENTATION_README.md (2)</summary><blockquote> `158-159`: All referenced source code files exist and are correctly identified. The files at `src/main/java/org/kpmp/OpenAPIConfiguration.java` and `src/main/java/org/kpmp/QueryController.java` are verified. OpenAPIConfiguration is a Spring @Configuration class for OpenAPI/Swagger documentation, and QueryController is a Spring GraphQL controller (implements GraphQLQueryResolver with @QueryMapping endpoints). --- `108-127`: **All anchor links in ENDPOINTS.md are valid and correctly reference existing sections.** Lines 108-127 of API_DOCUMENTATION_README.md contain four anchor-style links to ENDPOINTS.md within the code snippet, all of which have been verified to exist: - `#query-geneexpressionsummary--geneexpressionsummary2025` references `### Query: geneExpressionSummary / geneExpressionSummary2025` - `#query-celltypehierarchy` references `### Query: cellTypeHierarchy` - `#query-getumapplotdata--getumapplotdata2025` references `### Query: getUmapPlotData / getUmapPlotData2025` - `#query-getparticipantclinicaldataset` references `### Query: getParticipantClinicalDataset` All anchors match their target sections exactly and are case-sensitive-compliant according to GitHub markdown anchor rules where letters are converted to lowercase, spaces replaced by hyphens, and any other whitespace or punctuation characters removed. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| | Resource | URL | Best For | | ||
| |----------|-----|----------| | ||
| | **Swagger UI** | http://localhost:8080/swagger-ui.html | Exploring REST endpoints | | ||
| | **GraphQL IDE** | http://localhost:8080/graphiql | Testing GraphQL queries | | ||
| | **OpenAPI Spec** | http://localhost:8080/v3/api-docs | API specification | |
There was a problem hiding this comment.
Wrap bare URLs in markdown formatting.
Per markdownlint, bare URLs should be wrapped in markdown link syntax or code blocks. Lines 39-43 contain bare URLs in a table that should be formatted as proper markdown links or wrapped in backticks.
Apply this diff to fix bare URLs in the table:
| Resource | URL | Best For |
|----------|-----|----------|
- | **Swagger UI** | http://localhost:8080/swagger-ui.html | Exploring REST endpoints |
- | **GraphQL IDE** | http://localhost:8080/graphiql | Testing GraphQL queries |
- | **OpenAPI Spec** | http://localhost:8080/v3/api-docs | API specification |
+ | **Swagger UI** | `http://localhost:8080/swagger-ui.html` | Exploring REST endpoints |
+ | **GraphQL IDE** | `http://localhost:8080/graphiql` | Testing GraphQL queries |
+ | **OpenAPI Spec** | `http://localhost:8080/v3/api-docs` | API specification |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Resource | URL | Best For | | |
| |----------|-----|----------| | |
| | **Swagger UI** | http://localhost:8080/swagger-ui.html | Exploring REST endpoints | | |
| | **GraphQL IDE** | http://localhost:8080/graphiql | Testing GraphQL queries | | |
| | **OpenAPI Spec** | http://localhost:8080/v3/api-docs | API specification | | |
| | Resource | URL | Best For | | |
| |----------|-----|----------| | |
| | **Swagger UI** | `http://localhost:8080/swagger-ui.html` | Exploring REST endpoints | | |
| | **GraphQL IDE** | `http://localhost:8080/graphiql` | Testing GraphQL queries | | |
| | **OpenAPI Spec** | `http://localhost:8080/v3/api-docs` | API specification | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
41-41: Bare URL used
(MD034, no-bare-urls)
42-42: Bare URL used
(MD034, no-bare-urls)
43-43: Bare URL used
(MD034, no-bare-urls)
| - **Interactive Query Testing**: http://localhost:8080/graphiql | ||
| - **Swagger UI**: http://localhost:8080/swagger-ui.html | ||
| - **OpenAPI Spec**: http://localhost:8080/v3/api-docs | ||
| - **Server Health Check**: http://localhost:8080/actuator (if enabled) |
There was a problem hiding this comment.
Wrap bare URLs in markdown formatting.
Per markdownlint, bare URLs on lines 187-190 and 230 should be wrapped in backticks or markdown link syntax.
Apply this diff:
- **Interactive Query Testing**: http://localhost:8080/graphiql
- **Swagger UI**: http://localhost:8080/swagger-ui.html
- **OpenAPI Spec**: http://localhost:8080/v3/api-docs
- **Server Health Check**: http://localhost:8080/actuator (if enabled)
+ **Interactive Query Testing**: `http://localhost:8080/graphiql`
+ **Swagger UI**: `http://localhost:8080/swagger-ui.html`
+ **OpenAPI Spec**: `http://localhost:8080/v3/api-docs`
+ **Server Health Check**: `http://localhost:8080/actuator` (if enabled)
...
- 5. Contact KPMP team at https://www.kpmp.org
+ 5. Contact KPMP team at `https://www.kpmp.org`Also applies to: 230-230
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
187-187: Bare URL used
(MD034, no-bare-urls)
188-188: Bare URL used
(MD034, no-bare-urls)
189-189: Bare URL used
(MD034, no-bare-urls)
190-190: Bare URL used
(MD034, no-bare-urls)
| 1. Check the GraphQL schema at `/graphiql` | ||
| 2. View the Swagger documentation at `/swagger-ui.html` | ||
| 3. Review server logs for detailed error messages | ||
| 4. Contact the KPMP team at https://www.kpmp.org |
There was a problem hiding this comment.
Wrap bare URL in markdown formatting.
Per markdownlint, bare URL on line 239 should be wrapped in backticks or markdown link syntax.
Apply this diff:
- 4. Contact the KPMP team at https://www.kpmp.org
+ 4. Contact the KPMP team at [`https://www.kpmp.org`](https://www.kpmp.org)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 4. Contact the KPMP team at https://www.kpmp.org | |
| 4. Contact the KPMP team at [`https://www.kpmp.org`](https://www.kpmp.org) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
239-239: Bare URL used
(MD034, no-bare-urls)
| implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0' | ||
| implementation 'org.springdoc:springdoc-openapi-starter-webmvc-api:2.3.0' |
There was a problem hiding this comment.
Update springdoc-openapi dependencies to the latest stable version.
The dependencies are pinned to version 2.3.0, which is nearly two years old. The recommended stable version is 2.8.14. Upgrade both springdoc-openapi-starter-webmvc-ui and springdoc-openapi-starter-webmvc-api to 2.8.14 for better compatibility with Spring Boot 3.2.5 and access to improvements and fixes released since 2.3.0.
| method: 'POST', | ||
| headers: { 'Content-Type': 'application/json' }, | ||
| body: JSON.stringify({ query }) | ||
| }); |
There was a problem hiding this comment.
Add language specifications to fenced code blocks.
Per markdownlint (MD040), fenced code blocks should have a language specified. Several code blocks are missing language identifiers.
Apply this diff to add language tags:
- #### 1. Clear Cache
+ #### 1. Clear Cache
```http
GET /v1/clearCachePurpose: Refresh all cached data
Response:
-
{ "message": "Caches successfully cleared!", "cacheNames": ["gene-expression-cache", "umap-cache", "summary-cache"] }
-
**When to use:** - After data updates in the database - Testing to ensure fresh data - Troubleshooting cache-related issues #### 2. Log Error ```http POST /v1/error Content-Type: application/jsonRequest Body:
-
{ "error": "Failed to load gene expression data", "stackTrace": "Error at loadGeneData (app.js:125)\n at process.js:90" }
-
**Response:**
-
true
Also add language tags to other bare code blocks:
- Line 541 (ParticipantClinicalDataset): Add ````graphql` or use code fence with appropriate language
- Lines 550, 562, 579, 590, 600: Similar issues with response examples
Also applies to: 550-550, 562-562, 579-579, 590-590, 600-600
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
541-541: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<!-- fingerprinting:phantom:triton:mongoose -->
<!-- This is an auto-generated comment by CodeRabbit -->
| http://localhost:8080/swagger-ui.html | ||
| └─ Interactive Swagger UI | ||
| └─ Test REST endpoints | ||
| └─ View request/response schemas | ||
|
|
||
| 📊 GraphQL Query Documentation | ||
| http://localhost:8080/graphiql | ||
| └─ Interactive GraphQL IDE | ||
| └─ Explore schema | ||
| └─ Test queries | ||
| └─ Auto-completion | ||
|
|
||
| 📋 OpenAPI Specification | ||
| http://localhost:8080/v3/api-docs | ||
| └─ Machine-readable API spec | ||
| └─ Use for code generation | ||
| └─ View raw JSON format | ||
|
|
||
| 📋 OpenAPI Specification (YAML) | ||
| http://localhost:8080/v3/api-docs.yaml |
There was a problem hiding this comment.
Critical: Port references are incorrect throughout the documentation.
All interactive documentation URLs reference port 8080, but the application is configured to run on port 3030 (application.properties line 10: server.port=3030).
Update all URL references from port 8080 to 3030:
🔍 REST Endpoint Documentation
- http://localhost:8080/swagger-ui.html
+ http://localhost:3030/swagger-ui.html
└─ Interactive Swagger UI
└─ Test REST endpoints
└─ View request/response schemas
📊 GraphQL Query Documentation
- http://localhost:8080/graphiql
+ http://localhost:3030/graphiql
└─ Interactive GraphQL IDE
└─ Explore schema
└─ Test queries
└─ Auto-completion
📋 OpenAPI Specification
- http://localhost:8080/v3/api-docs
+ http://localhost:3030/v3/api-docs
└─ Machine-readable API spec
└─ Use for code generation
└─ View raw JSON format
📋 OpenAPI Specification (YAML)
- http://localhost:8080/v3/api-docs.yaml
+ http://localhost:3030/v3/api-docs.yamlAlso update references on lines 157-158 and 224-226.
Committable suggestion skipped: line range outside the PR's diff.
| $ curl -X POST http://localhost:8080/graphql \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"query": "query { autocomplete(searchTerm: \"APOL\") { label } }"}' |
There was a problem hiding this comment.
Update example curl command to use correct port.
The quick start example references port 8080 instead of 3030.
4. Make your first request
- $ curl -X POST http://localhost:8080/graphql \
+ $ curl -X POST http://localhost:3030/graphql \
-H "Content-Type: application/json" \
-d '{"query": "query { autocomplete(searchTerm: \"APOL\") { label } }"}'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| $ curl -X POST http://localhost:8080/graphql \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"query": "query { autocomplete(searchTerm: \"APOL\") { label } }"}' | |
| $ curl -X POST http://localhost:3030/graphql \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"query": "query { autocomplete(searchTerm: \"APOL\") { label } }"}' |
| * - Swagger UI: http://localhost:8080/swagger-ui.html | ||
| * - OpenAPI JSON: http://localhost:8080/v3/api-docs | ||
| * - OpenAPI YAML: http://localhost:8080/v3/api-docs.yaml |
There was a problem hiding this comment.
Update JavaDoc to reflect correct port configuration.
The JavaDoc comment references port 8080, but should reference port 3030 to match the application configuration.
Apply this diff:
* Access the generated documentation at:
- * - Swagger UI: http://localhost:8080/swagger-ui.html
- * - OpenAPI JSON: http://localhost:8080/v3/api-docs
- * - OpenAPI YAML: http://localhost:8080/v3/api-docs.yaml
+ * - Swagger UI: http://localhost:3030/swagger-ui.html
+ * - OpenAPI JSON: http://localhost:3030/v3/api-docs
+ * - OpenAPI YAML: http://localhost:3030/v3/api-docs.yaml📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| * - Swagger UI: http://localhost:8080/swagger-ui.html | |
| * - OpenAPI JSON: http://localhost:8080/v3/api-docs | |
| * - OpenAPI YAML: http://localhost:8080/v3/api-docs.yaml | |
| * Access the generated documentation at: | |
| * - Swagger UI: http://localhost:3030/swagger-ui.html | |
| * - OpenAPI JSON: http://localhost:3030/v3/api-docs | |
| * - OpenAPI YAML: http://localhost:3030/v3/api-docs.yaml |
| .url("http://localhost:8080") | ||
| .description("Local Development Server")) |
There was a problem hiding this comment.
Critical: Hardcoded port 8080 conflicts with application configuration.
The development server URL is hardcoded to port 8080, but application.properties configures server.port=3030. This creates a critical mismatch where all generated OpenAPI documentation will reference incorrect URLs.
Consider injecting the server port from application properties instead of hardcoding:
+import org.springframework.beans.factory.annotation.Value;
+
@Configuration
public class OpenAPIConfiguration {
+ @Value("${server.port:8080}")
+ private int serverPort;
+
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
// ... info configuration ...
)
.addServersItem(new Server()
- .url("http://localhost:8080")
+ .url("http://localhost:" + serverPort)
.description("Local Development Server"))
.addServersItem(new Server()
.url("https://pegasus-data.kpmp.org")
.description("Production Server"));
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| .url("http://localhost:8080") | |
| .description("Local Development Server")) | |
| import org.springframework.beans.factory.annotation.Value; | |
| @Configuration | |
| public class OpenAPIConfiguration { | |
| @Value("${server.port:8080}") | |
| private int serverPort; | |
| @Bean | |
| public OpenAPI customOpenAPI() { | |
| return new OpenAPI() | |
| .info(new Info() | |
| // ... info configuration ... | |
| ) | |
| .addServersItem(new Server() | |
| .url("http://localhost:" + serverPort) | |
| .description("Local Development Server")) | |
| .addServersItem(new Server() | |
| .url("https://pegasus-data.kpmp.org") | |
| .description("Production Server")); | |
| } | |
| } |
| # Swagger/OpenAPI Configuration | ||
| springdoc.swagger-ui.enabled=true | ||
| springdoc.swagger-ui.path=/swagger-ui.html | ||
| springdoc.api-docs.path=/v3/api-docs | ||
| springdoc.api-docs.enabled=true | ||
| springdoc.swagger-ui.try-it-out-enabled=true | ||
| springdoc.swagger-ui.display-operation-id=true | ||
| springdoc.swagger-ui.doc-expansion=list |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find all references to ports 8080 and 3030
echo "=== Searching for port 8080 references ==="
rg -n "8080" -t md -t java -t properties -t txt 2>/dev/null || echo "No 8080 references found"
echo -e "\n=== Searching for port 3030 references ==="
rg -n "3030" -t md -t java -t properties -t txt 2>/dev/null || echo "No 3030 references found"
echo -e "\n=== Searching for server.port in properties files ==="
rg -n "server\.port" -t properties 2>/dev/null || echo "No server.port found"Repository: KPMP/pegasus-data
Length of output: 273
🏁 Script executed:
#!/bin/bash
# Check if application.properties exists and read relevant lines
echo "=== Reading application.properties ==="
if [ -f "src/main/resources/application.properties" ]; then
echo "File found. Reading lines 1-25:"
head -25 src/main/resources/application.properties | cat -n
else
echo "application.properties not found at expected path"
# Try to find it
fd "application.properties" 2>/dev/null | head -5
fiRepository: KPMP/pegasus-data
Length of output: 1351
🏁 Script executed:
#!/bin/bash
# Find and examine OpenAPIConfiguration.java
echo "=== Locating OpenAPIConfiguration.java ==="
fd "OpenAPIConfiguration.java" 2>/dev/null
echo -e "\n=== Checking for port references in OpenAPIConfiguration files ==="
fd "OpenAPIConfiguration.java" -x cat -n {} \; 2>/dev/null | grep -A 5 -B 5 "8080\|3030\|localhost"Repository: KPMP/pegasus-data
Length of output: 1365
🏁 Script executed:
#!/bin/bash
# Check for documentation files mentioned
echo "=== Checking for documentation files ==="
fd "DOCUMENTATION_MAP.txt" 2>/dev/null
fd "DOCUMENTATION_IMPLEMENTATION.md" 2>/dev/null
echo -e "\n=== Searching for any localhost references with port numbers ==="
rg "localhost:[0-9]+" -n 2>/dev/null | head -20Repository: KPMP/pegasus-data
Length of output: 1805
Critical: Port inconsistency breaks Swagger UI interactivity.
The application is configured to run on port 3030 (src/main/resources/application.properties line 10), but OpenAPIConfiguration.java (line 67) hardcodes port 8080 in the OpenAPI server configuration. This will cause the Swagger UI "Try it out" feature to attempt requests to the wrong port, breaking all interactive API testing.
Additionally, multiple documentation files reference the incorrect port:
- DOCUMENTATION_MAP.txt
- DOCUMENTATION_IMPLEMENTATION.md
- ENDPOINTS.md
- DEVELOPER_GUIDE.md
Apply this diff to src/main/java/org/kpmp/OpenAPIConfiguration.java line 67:
- .url("http://localhost:8080")
+ .url("http://localhost:3030")Also update all documentation files to reference port 3030 instead of 8080.
Committable suggestion skipped: line range outside the PR's diff.
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.