Skip to content

Commit 348d1c1

Browse files
author
springdoc
committed
project review
1 parent bd207a8 commit 348d1c1

File tree

10 files changed

+203
-46
lines changed

10 files changed

+203
-46
lines changed

‎docs/index.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ This library supports:
3434
<dependency>
3535
<groupId>org.springdoc</groupId>
3636
<artifactId>springdoc-openapi-ui</artifactId>
37-
<version>1.1.6</version>
37+
<version>1.1.11</version>
3838
</dependency>
3939
```
4040
* This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:
@@ -64,7 +64,7 @@ springdoc.swagger-ui.path=/swagger-ui.html
6464
<dependency>
6565
<groupId>org.springdoc</groupId>
6666
<artifactId>springdoc-openapi-core</artifactId>
67-
<version>1.1.6</version>
67+
<version>1.1.11</version>
6868
</dependency>
6969
```
7070
* This step is optional: For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:
@@ -89,7 +89,7 @@ To generate documentation automatically, make sure all the methods declare the H
8989
<dependency>
9090
<groupId>org.springdoc</groupId>
9191
<artifactId>springdoc-openapi-webflux-ui</artifactId>
92-
<version>1.1.6</version>
92+
<version>1.1.11</version>
9393
</dependency>
9494
```
9595
* This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:

‎docs/pom.xml

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<project xmlns="http://maven.apache.org/POM/4.0.0"
2+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
4+
<modelVersion>4.0.0</modelVersion>
5+
<artifactId>docs</artifactId>
6+
<packaging>jar</packaging>
7+
<name>${project.artifactId}</name>
8+
<parent>
9+
<groupId>org.springdoc</groupId>
10+
<artifactId>springdoc-openapi-demos</artifactId>
11+
<version>3.1.1-SNAPSHOT</version>
12+
</parent>
13+
14+
<build>
15+
<plugins>
16+
<plugin>
17+
<artifactId>maven-resources-plugin</artifactId>
18+
<version>3.1.0</version>
19+
<executions>
20+
<execution>
21+
<id>copy-resources</id>
22+
<phase>validate</phase>
23+
<goals>
24+
<goal>copy-resources</goal>
25+
</goals>
26+
<configuration>
27+
<outputDirectory>${project.basedir}</outputDirectory>
28+
<resources>
29+
<resource>
30+
<directory>src/main/resources</directory>
31+
<filtering>true</filtering>
32+
</resource>
33+
</resources>
34+
</configuration>
35+
</execution>
36+
</executions>
37+
</plugin>
38+
</plugins>
39+
</build>
40+
41+
</project>

‎docs/src/main/resources/index.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
layout: default
3+
---
4+
![Octocat](https://springdoc.github.io/springdoc-openapi-demos/images/springdoc-openapi.png)
5+
6+
# **Introduction**
7+
8+
springdoc-openapi java library helps automating the generation of API documentation using spring boot projects.
9+
springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.
10+
11+
Automatically generates documentation in JSON/YAML and HTML format APIs.
12+
This documentation can be completed by comments using swagger-api annotations.
13+
14+
This library supports:
15+
* OpenAPI 3
16+
* Spring-boot (v1 and v2)
17+
* JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
18+
* Swagger-ui
19+
* Oauth 2
20+
21+
# **Getting Started**
22+
23+
## Library for springdoc-openapi integration with spring-boot and swagger-ui
24+
* Automatically deploys swagger-ui to a spring-boot 2 application
25+
* Documentation will be available in HTML format, using the official [swagger-ui jars]: (https://github.com/swagger-api/swagger-ui.git).
26+
* The Swagger UI page should then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs
27+
* server: The server name or IP
28+
* port: The server port
29+
* context-path: The context path of the application
30+
* Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yml
31+
* Add the library to the list of your project dependencies (No additional configuration is needed)
32+
33+
```xml
34+
<dependency>
35+
<groupId>org.springdoc</groupId>
36+
<artifactId>springdoc-openapi-ui</artifactId>
37+
<version>@springdoc.version@</version>
38+
</dependency>
39+
```
40+
* This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:
41+
42+
```properties
43+
# swagger-ui custom path
44+
springdoc.swagger-ui.path=/swagger-ui.html
45+
```
46+
47+
## [Demo application 1](https://springdoc-openapi-test-app2-silly-numbat.eu-de.mybluemix.net/).
48+
## [Demo application 2](https://springdoc-openapi-test-app1-courteous-puku.eu-de.mybluemix.net/).
49+
50+
![Branching](https://springdoc.github.io/springdoc-openapi-demos/images/pets.png)
51+
52+
## Source code of the Demo Applications
53+
* https://github.com/springdoc/springdoc-openapi-demos.git
54+
55+
## Integration of the libray in a spring-boot 2 project without the swagger-ui:
56+
* Documentation will be available at the following url for json format: http://server:port/context-path/v3/api-docs
57+
* server: The server name or IP
58+
* port: The server port
59+
* context-path: The context path of the application
60+
* Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yml
61+
* Add the library to the list of your project dependencies. (No additional configuration is needed)
62+
63+
```xml
64+
<dependency>
65+
<groupId>org.springdoc</groupId>
66+
<artifactId>springdoc-openapi-core</artifactId>
67+
<version>@springdoc.version@</version>
68+
</dependency>
69+
```
70+
* This step is optional: For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:
71+
72+
```properties
73+
# /api-docs endpoint custom path
74+
springdoc.api-docs.path=/api-docs
75+
```
76+
77+
## Adding API Information documentation
78+
The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info.
79+
These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs
80+
81+
## Error Handling for REST using @ControllerAdvice
82+
To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus
83+
84+
## spring-weblfux support with Annotated Controllers
85+
* Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yml
86+
* Add the library to the list of your project dependencies (No additional configuration is needed)
87+
88+
```xml
89+
<dependency>
90+
<groupId>org.springdoc</groupId>
91+
<artifactId>springdoc-openapi-webflux-ui</artifactId>
92+
<version>@springdoc.version@</version>
93+
</dependency>
94+
```
95+
* This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:
96+
97+
```properties
98+
# swagger-ui custom path
99+
springdoc.swagger-ui.path=/swagger-ui.html
100+
```
101+
102+
## spring-weblfux with Functional Endpoints, will be available in the future release
103+
## Dependencies repository
104+
105+
The springdoc-openapi libraries are hosted on maven central repository.
106+
The artifacts can be viewed accessed at the following locations:
107+
108+
Releases:
109+
* [https://oss.sonatype.org/content/groups/public/org/springdoc/](https://oss.sonatype.org/content/groups/public/org/springdoc/).
110+
111+
Snapshots:
112+
* [https://oss.sonatype.org/content/repositories/snapshots/org/springdoc/](https://oss.sonatype.org/content/repositories/snapshots/org/springdoc/).
113+
114+
115+
116+
117+
118+

‎docs/target/javadoc-bundle-options/javadoc-options-javadoc-resources.xml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<javadocOptions>
3+
<docletArtifacts>
4+
<docletArtifact />
5+
</docletArtifacts>
6+
<tagletArtifacts>
7+
<tagletArtifact />
8+
</tagletArtifacts>
9+
<javadocResourcesDirectory>src/main/javadoc</javadocResourcesDirectory>
10+
</javadocOptions>

‎docs/target/maven-archiver/pom.properties

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#Generated by Maven
2+
#Fri Aug 09 21:40:23 CEST 2019
3+
version=3.1.1-SNAPSHOT
4+
groupId=org.springdoc
5+
artifactId=docs

‎manifest.yml

+8
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,11 @@ applications:
1616
JAVA_OPTS: '-XX:MaxMetaspaceSize=80780K -Xss512k -Xmx200M -XX:ReservedCodeCacheSize=16M -XX:MaxDirectMemorySize=16M'
1717
JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 1.8.0_212 } }'
1818
buildpack: java_buildpack
19+
- name: springdoc-openapi-test-app3
20+
random-route: true
21+
memory: 400m
22+
path: springdoc-openapi-test-app3-cf.jar
23+
env:
24+
JAVA_OPTS: '-XX:MaxMetaspaceSize=80780K -Xss512k -Xmx200M -XX:ReservedCodeCacheSize=16M -XX:MaxDirectMemorySize=16M'
25+
JBP_CONFIG_OPEN_JDK_JRE: '{ jre: { version: 1.8.0_212 } }'
26+
buildpack: java_buildpack

‎pom.xml

+16-1
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
<module>springdoc-openapi-test-app1</module>
4848
<module>springdoc-openapi-test-app2</module>
4949
<module>springdoc-openapi-test-app3</module>
50+
<module>docs</module>
5051
</modules>
5152

5253
<properties>
@@ -68,7 +69,8 @@
6869
<nexus-staging-maven-plugin>1.6.8</nexus-staging-maven-plugin>
6970
<jacoco-maven-plugin.version>0.8.3</jacoco-maven-plugin.version>
7071
<resource.delimiter>@</resource.delimiter>
71-
<springdoc.version>1.1.7</springdoc.version>
72+
<springdoc.version>1.1.11</springdoc.version>
73+
<spring-boot.version>2.0.9.RELEASE</spring-boot.version>
7274
</properties>
7375

7476
<dependencyManagement>
@@ -84,6 +86,13 @@
8486
<artifactId>springdoc-openapi-webflux-ui</artifactId>
8587
<version>${springdoc.version}</version>
8688
</dependency>
89+
<dependency>
90+
<groupId>org.springframework.boot</groupId>
91+
<artifactId>spring-boot-dependencies</artifactId>
92+
<version>${spring-boot.version}</version>
93+
<type>pom</type>
94+
<scope>import</scope>
95+
</dependency>
8796
</dependencies>
8897
</dependencyManagement>
8998
<build>
@@ -160,6 +169,12 @@
160169
</plugin>
161170
</plugins>
162171
</pluginManagement>
172+
<resources>
173+
<resource>
174+
<directory>src/main/resources</directory>
175+
<filtering>true</filtering>
176+
</resource>
177+
</resources>
163178
</build>
164179

165180

‎springdoc-openapi-test-app1/pom.xml

-11
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,6 @@
1111
<properties>
1212
<spring-boot.version>1.5.21.RELEASE</spring-boot.version>
1313
</properties>
14-
<dependencyManagement>
15-
<dependencies>
16-
<dependency>
17-
<groupId>org.springframework.boot</groupId>
18-
<artifactId>spring-boot-dependencies</artifactId>
19-
<version>${spring-boot.version}</version>
20-
<type>pom</type>
21-
<scope>import</scope>
22-
</dependency>
23-
</dependencies>
24-
</dependencyManagement>
2514
<dependencies>
2615
<dependency>
2716
<groupId>org.springframework.boot</groupId>

‎springdoc-openapi-test-app2/pom.xml

+1-15
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,6 @@
88
<artifactId>springdoc-openapi-demos</artifactId>
99
<version>3.1.1-SNAPSHOT</version>
1010
</parent>
11-
<properties>
12-
<spring-boot.version>2.0.9.RELEASE</spring-boot.version>
13-
</properties>
14-
<dependencyManagement>
15-
<dependencies>
16-
<dependency>
17-
<groupId>org.springframework.boot</groupId>
18-
<artifactId>spring-boot-dependencies</artifactId>
19-
<version>${spring-boot.version}</version>
20-
<type>pom</type>
21-
<scope>import</scope>
22-
</dependency>
23-
</dependencies>
24-
</dependencyManagement>
2511
<dependencies>
2612
<dependency>
2713
<groupId>org.springframework.boot</groupId>
@@ -59,4 +45,4 @@
5945
</plugin>
6046
</plugins>
6147
</build>
62-
</project>
48+
</project>

‎springdoc-openapi-test-app3/pom.xml

+1-16
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,6 @@
1010
<artifactId>springdoc-openapi-demos</artifactId>
1111
<version>3.1.1-SNAPSHOT</version>
1212
</parent>
13-
<properties>
14-
<spring-boot.version>2.0.9.RELEASE</spring-boot.version>
15-
</properties>
16-
<dependencyManagement>
17-
<dependencies>
18-
<dependency>
19-
<groupId>org.springframework.boot</groupId>
20-
<artifactId>spring-boot-dependencies</artifactId>
21-
<version>${spring-boot.version}</version>
22-
<type>pom</type>
23-
<scope>import</scope>
24-
</dependency>
25-
</dependencies>
26-
</dependencyManagement>
2713
<dependencies>
2814
<!-- springdoc ui -->
2915
<dependency>
@@ -60,7 +46,6 @@
6046
<optional>true</optional>
6147
</dependency>
6248
</dependencies>
63-
6449
<build>
6550
<plugins>
6651
<plugin>
@@ -76,4 +61,4 @@
7661
</plugin>
7762
</plugins>
7863
</build>
79-
</project>
64+
</project>

0 commit comments

Comments
 (0)