From ecf4ff79168d9a1ed91d943d1d07081f06ae51e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Fr=C4=85k?= Date: Tue, 4 Feb 2020 09:03:18 +0100 Subject: [PATCH] Readme.md --- README.md | 52 +++++++++++++++++++++++++++++++++++++++++ readme-images/logo.png | Bin 0 -> 10137 bytes 2 files changed, 52 insertions(+) create mode 100644 README.md create mode 100644 readme-images/logo.png diff --git a/README.md b/README.md new file mode 100644 index 0000000..28bd829 --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# Springdoc OpenAPI Programmatic Documentation library + +![Code Soapbox logo](readme-images/logo.png) + +## Introduction + +This library is an extension for *Springdoc OpenAPI* which allows for defining OpenAPI 3.0 schema using code. + +However, while it was developed with *Springdoc OpenAPI* in mind, **you can apply this solution to any +Spring Boot OpenAPI library based on Spring Core**. + +## Getting Started + +1. Add a dependency on `springdoc-openapi-programmatic-documentation`: + +```xml + + com.danielfrak.code + springdoc-openapi-programmatic-documentation + 1.0.1 + +``` + +2. Inject a `ModelDocumentation` instance in a `@configuration` class and use it to add a new schema: + +```java +import io.swagger.v3.oas.models.media.Schema; +import org.springframework.context.annotation.Configuration; +import com.danielfrak.code.config.openapi.ModelDocumentation; +import com.danielfrak.code.config.openapi.ModelDocumentation.Model; +import com.danielfrak.code.model.MyValueObject; + +@Configuration +public class OpenApiConfig { + + public OpenApiConfig(ModelDocumentation modelDocumentation) { + modelDocumentation + .add(new DocumentedModel() + .source(MyValueObject.class) + .implementation(String.class) + .schema(new Schema<>() + .example("Example value") + .description("Base description"))); + } +} +``` + +## DocumentedModel fields + +* `source` - the class to document +* `implementation` - equivalent to the `implementation` on `@io.swagger.v3.oas.annotations.media.Schema` +* `schema` - an `io.swagger.v3.oas.models.media.Schema` instance to serve as the final schema for the source class \ No newline at end of file diff --git a/readme-images/logo.png b/readme-images/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..fba2503ee1c94b89c4b5d357643c159aaf7b1c34 GIT binary patch literal 10137 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 H?iBSuVScm3 literal 0 HcmV?d00001