spring-boot-openapi-documentation

Name: spring-boot-openapi-documentation
Author: giuseppe-trisciuoglio

1.8kinstalls36forks

How to install spring-boot-openapi-documentation?

giuseppe-trisciuoglio/developer-kit/spring-boot-openapi-documentation

$npx -y skills add giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation

Installs into the current project.

Summary

Provides patterns to generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or enhanc

Files · 1

View on GitHub

SKILL.md

1	# Spring Boot OpenAPI Documentation with SpringDoc
2
3	## Overview
4
5	SpringDoc OpenAPI automates generation of OpenAPI 3.0 documentation for Spring Boot projects with a Swagger UI web interface for exploring and testing APIs.
6
7	## When to Use
8
9	- Set up SpringDoc OpenAPI in Spring Boot 3.x projects
10	- Generate OpenAPI 3.0 specifications for REST APIs
11	- Configure and customize Swagger UI
12	- Add detailed API documentation with annotations
13	- Document request/response models with validation
14	- Implement API security documentation (JWT, OAuth2, Basic Auth)
15	- Document pageable and sortable endpoints
16	- Add examples and schemas to API endpoints
17	- Customize OpenAPI definitions programmatically
18	- Support multiple API groups and versions
19	- Document error responses and exception handlers
20	- Add JSR-303 Bean Validation to API documentation
21	- Support Kotlin-based Spring Boot APIs
22
23	## Quick Reference
24
25	\| Concept \| Description \|
26	\|---------\|-------------\|
27	\| Dependencies \| `springdoc-openapi-starter-webmvc-ui` for WebMvc, `springdoc-openapi-starter-webflux-ui` for WebFlux \|
28	\| Configuration \| `application.yml` with `springdoc.api-docs.` and `springdoc.swagger-ui.` properties \|
29	\| Access Points \| OpenAPI JSON: `/v3/api-docs`, Swagger UI: `/swagger-ui/index.html` \|
30	\| Core Annotations \| `@Tag`, `@Operation`, `@ApiResponse`, `@Parameter`, `@Schema`, `@SecurityRequirement` \|
31	\| Security \| Configure security schemes in OpenAPI bean, apply with `@SecurityRequirement` \|
32	\| Pagination \| Use `@ParameterObject` with Spring Data `Pageable` \|
33
34	## Instructions
35
36	### 1. Add Dependencies
37
38	Add SpringDoc starter for your application type (WebMvc or WebFlux). See [dependency-setup.md](references/dependency-setup.md) for Maven/Gradle configuration.
39
40	### 2. Configure SpringDoc
41
42	Set basic configuration in `application.yml`:
43
44	```yaml
45	springdoc:
46	api-docs:
47	path: /api-docs
48	swagger-ui:
49	path: /swagger-ui.html
50	operationsSorter: method
51	```
52
53	See [configuration.md](references/configuration.md) for advanced options.
54
55	### 3. Document Controllers
56
57	Use OpenAPI annotations to add descriptive information:
58
59	```java
60	@RestController
61	@Tag(name = "Book", description = "Book management APIs")
62	public class BookController {
63
64	@Operation(summary = "Get book by ID")
65	@ApiResponse(responseCode = "200", description = "Book found")
66	@GetMapping("/{id}")
67	public Book findById(@PathVariable Long id) { }
68	}
69	```
70
71	See [controller-documentation.md](references/controller-documentation.md) for patterns.
72
73	### 4. Document Models
74
75	Apply `@Schema` annotations to DTOs:
76
77	```java
78	@Schema(description = "Book entity")
79	public class Book {
80	@Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
81	private Long id;
82
83	@Schema(example = "Clean Code", required = true)
84	private String title;
85	}
86	```
87
88	See [model-documentation.md](references/model-documentation.md) for validation patterns.
89
90	### 5. Configure Security
91
92	Set up security schemes in OpenAPI bean:
93
94	```java
95	@Bean
96	public OpenAPI customOpenAPI() {
97	return new OpenAPI()
98	.components(new Components()
99	.addSecuritySchemes("bearer-jwt", new SecurityScheme()
100	.type(SecurityScheme.Type.HTTP)
101	.scheme("bearer")
102	.bearerFormat("JWT")
103	)
104	);
105	}
106	```
107
108	Apply with `@SecurityRequirement(name = "bearer-jwt")` on controllers. See [security-configuration.md](references/security-configuration.md).
109
110	### 6. Document Pagination
111
112	Use `@ParameterObject` for Spring Data `Pageable`:
113
114	```java
115	@GetMapping("/paginated")
116	public Page<Book> findAll(@ParameterObject Pageable pageable) {
117	return repository.findAll(pageable);
118	}
119	```
120
121	See [pagination-support.md](references/pagination-support.md).
122
123	### 7. Test Documentation
124
125	Access Swagger UI at `/swagger-ui/index.html` to verify documentation completeness.
126
127	### 8. Customize for Production
128
129	Configure API grouping, versioning, and build plugins. See [advanced-configuration.md](references/advanced-configuration.md) and [build-integration.md](references/build-integration.md).
130
131	## Best Practices
132
133	- Use descriptive operation summaries: Short (< 120 chars), clear statements
134	- Document all response codes: Include success (2xx), client errors (4xx), server errors (5xx)
135	- Add examples to request/response bodies: Use `@ExampleObject` for realistic examples
136	- Leverage JSR-303 validation annotations: SpringDoc auto-generates constraints from validation annotations
137	- Use `@ParameterObject` for complex parameters: Especially for Pageable, custom filter ob

People who liked this also viewed

6 picks

Type

spring-boot-openapi-documentation

1.8kinstalls36forks

View on GitHub

How to install spring-boot-openapi-documentation?

giuseppe-trisciuoglio/developer-kit/spring-boot-openapi-documentation

$npx -y skills add giuseppe-trisciuoglio/developer-kit --skill spring-boot-openapi-documentation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Spring Boot OpenAPI Documentation with SpringDoc
2
3	## Overview
4
5	SpringDoc OpenAPI automates generation of OpenAPI 3.0 documentation for Spring Boot projects with a Swagger UI web interface for exploring and testing APIs.
6
7	## When to Use
8
9	- Set up SpringDoc OpenAPI in Spring Boot 3.x projects
10	- Generate OpenAPI 3.0 specifications for REST APIs
11	- Configure and customize Swagger UI
12	- Add detailed API documentation with annotations
13	- Document request/response models with validation
14	- Implement API security documentation (JWT, OAuth2, Basic Auth)
15	- Document pageable and sortable endpoints
16	- Add examples and schemas to API endpoints
17	- Customize OpenAPI definitions programmatically
18	- Support multiple API groups and versions
19	- Document error responses and exception handlers
20	- Add JSR-303 Bean Validation to API documentation
21	- Support Kotlin-based Spring Boot APIs
22
23	## Quick Reference
24
25	\| Concept \| Description \|
26	\|---------\|-------------\|
27	\| Dependencies \| `springdoc-openapi-starter-webmvc-ui` for WebMvc, `springdoc-openapi-starter-webflux-ui` for WebFlux \|
28	\| Configuration \| `application.yml` with `springdoc.api-docs.` and `springdoc.swagger-ui.` properties \|
29	\| Access Points \| OpenAPI JSON: `/v3/api-docs`, Swagger UI: `/swagger-ui/index.html` \|
30	\| Core Annotations \| `@Tag`, `@Operation`, `@ApiResponse`, `@Parameter`, `@Schema`, `@SecurityRequirement` \|
31	\| Security \| Configure security schemes in OpenAPI bean, apply with `@SecurityRequirement` \|
32	\| Pagination \| Use `@ParameterObject` with Spring Data `Pageable` \|
33
34	## Instructions
35
36	### 1. Add Dependencies
37
38	Add SpringDoc starter for your application type (WebMvc or WebFlux). See [dependency-setup.md](references/dependency-setup.md) for Maven/Gradle configuration.
39
40	### 2. Configure SpringDoc
41
42	Set basic configuration in `application.yml`:
43
44	```yaml
45	springdoc:
46	api-docs:
47	path: /api-docs
48	swagger-ui:
49	path: /swagger-ui.html
50	operationsSorter: method
51	```
52
53	See [configuration.md](references/configuration.md) for advanced options.
54
55	### 3. Document Controllers
56
57	Use OpenAPI annotations to add descriptive information:
58
59	```java
60	@RestController
61	@Tag(name = "Book", description = "Book management APIs")
62	public class BookController {
63
64	@Operation(summary = "Get book by ID")
65	@ApiResponse(responseCode = "200", description = "Book found")
66	@GetMapping("/{id}")
67	public Book findById(@PathVariable Long id) { }
68	}
69	```
70
71	See [controller-documentation.md](references/controller-documentation.md) for patterns.
72
73	### 4. Document Models
74
75	Apply `@Schema` annotations to DTOs:
76
77	```java
78	@Schema(description = "Book entity")
79	public class Book {
80	@Schema(example = "1", accessMode = Schema.AccessMode.READ_ONLY)
81	private Long id;
82
83	@Schema(example = "Clean Code", required = true)
84	private String title;
85	}
86	```
87
88	See [model-documentation.md](references/model-documentation.md) for validation patterns.
89
90	### 5. Configure Security
91
92	Set up security schemes in OpenAPI bean:
93
94	```java
95	@Bean
96	public OpenAPI customOpenAPI() {
97	return new OpenAPI()
98	.components(new Components()
99	.addSecuritySchemes("bearer-jwt", new SecurityScheme()
100	.type(SecurityScheme.Type.HTTP)
101	.scheme("bearer")
102	.bearerFormat("JWT")
103	)
104	);
105	}
106	```
107
108	Apply with `@SecurityRequirement(name = "bearer-jwt")` on controllers. See [security-configuration.md](references/security-configuration.md).
109
110	### 6. Document Pagination
111
112	Use `@ParameterObject` for Spring Data `Pageable`:
113
114	```java
115	@GetMapping("/paginated")
116	public Page<Book> findAll(@ParameterObject Pageable pageable) {
117	return repository.findAll(pageable);
118	}
119	```
120
121	See [pagination-support.md](references/pagination-support.md).
122
123	### 7. Test Documentation
124
125	Access Swagger UI at `/swagger-ui/index.html` to verify documentation completeness.
126
127	### 8. Customize for Production
128
129	Configure API grouping, versioning, and build plugins. See [advanced-configuration.md](references/advanced-configuration.md) and [build-integration.md](references/build-integration.md).
130
131	## Best Practices
132
133	- Use descriptive operation summaries: Short (< 120 chars), clear statements
134	- Document all response codes: Include success (2xx), client errors (4xx), server errors (5xx)
135	- Add examples to request/response bodies: Use `@ExampleObject` for realistic examples
136	- Leverage JSR-303 validation annotations: SpringDoc auto-generates constraints from validation annotations
137	- Use `@ParameterObject` for complex parameters: Especially for Pageable, custom filter ob

People who liked this also viewed

6 picks

Type