diff --git a/docs/faq.md b/docs/faq.md index c7e1522e..e2f3a178 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -3,19 +3,17 @@ layout: default --- # Welcome to FAQ -### How can i define multiple OpenAPI definitions in one Spring Boot project? -You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique groupName. +### How can I define multiple OpenAPI definitions in one Spring Boot project? +You can define your own groups of API based on the combination of: API paths and packages to scan. Each group should have a unique `groupName`. The OpenAPI description of this group, will be available by default on: - http://server:port/context-path/v3/api-docs/groupName -To enable this feature, the following springdoc property needs to be added to your application.yml: - - To enable this feature, the following springdoc property needs to be added to your application.yml: + To enable this feature, the following property needs to be added to your `application.properties`: ```properties springdoc.api-docs.groups.enabled=true ``` - For the support of multiple OpenAPI definitions, a bean of type GroupedOpenApi needs to be defined. + For the support of multiple OpenAPI definitions, a bean of type `GroupedOpenApi` needs to be defined. For the following Group definition(based on package path), the OpenAPI description url will be : /v3/api-docs/**stores** ```java @@ -62,23 +60,23 @@ For more details about the usage, you can have a look at the following sample Te - https://github.com/springdoc/springdoc-openapi/tree/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app68 -### How can i filter the resources documented in the output specification by the provided group? -- You can use the stand swagger-ui property filter. +### How can I filter the resources documented in the output specification by the provided group? +- You can use the standard `swagger-ui` property filter. ```properties -springdoc.swagger-ui.filter= group-a +springdoc.swagger-ui.filter=group-a ``` -### How can i add Reusable Enums ? -- You should add @Schema(enumAsRef = true) on your enum. +### How can I add Reusable Enums ? +- You should add `@Schema(enumAsRef = true)` on your enum. -### How can i change the layout of the swagger-ui ? +### How can I change the layout of the `swagger-ui`? - For layout options, you can use swagger-ui configuration options. For example: ```properties springdoc.swagger-ui.layout=BaseLayout ``` -### How can i sort endpoints alphabetically? -- You can use the following springdoc-openapi properties: +### How can I sort endpoints alphabetically? +- You can use the following `springdoc-openapi` properties: ```properties #For sorting endpoints alphabetically springdoc.swagger-ui.operationsSorter=alpha @@ -86,33 +84,33 @@ springdoc.swagger-ui.operationsSorter=alpha springdoc.swagger-ui.tagsSorter=alpha ``` -### How can i disable the try it out button? +### How can I disable the try it out button? - You have to set the following property: ```properties springdoc.swagger-ui.supportedSubmitMethods="get", "put", "post", "delete", "options", "head", "patch", "trace" ``` -### How can i eplicitly set which paths to filter? +### How can I explicitly set which paths to filter? - You can set list of paths to include using the following property: ```properties springdoc.pathsToMatch=/v1, /api/balance/** ``` -### How can i eplicitly set which packages to scan? +### How can I explicitly set which packages to scan? - You can set list of packages to include using the following property: ```properties springdoc.packagesToScan=package1, package2 ``` -### How can i ignore some field of model ? +### How can I ignore some field of model ? - You can use the following annotation on the top of the field that you want to hide: - - @Schema(hidden = true) + - `@Schema(hidden = true)` -### How can i ignore @AuthenticationPrincipal parameter from spring-security ? -- A solution workaround would be to use: @Parameter(hidden = true) -- For a project that uses spring-security, you should add the follwing dependency, together with the springdoc-openapi-ui dependency: +### How can I ignore `@AuthenticationPrincipal` parameter from spring-security ? +- A solution workaround would be to use: `@Parameter(hidden = true)` +- For a project that uses `spring-security`, you should add the following dependency, together with the `springdoc-openapi-ui` dependency: ```xml @@ -123,45 +121,45 @@ springdoc.packagesToScan=package1, package2 ``` ### Is there a gradle plugin available? -- There is no springdoc-gradle-plugin planned for short term. +- There is no `springdoc-gradle-plugin` planned for short term. -### How can i configure Swagger UI? -- The support of the swagger official properties is available on springdoc-openapi. [Official doc](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/). +### How can I configure Swagger UI? +- The support of the swagger official properties is available on `springdoc-openapi`. See [Official documentation](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/). -- You can use the same swagger properties in the documentation as spring-boot properties. -All these properties should be declared with the following prefix: **springdoc.swagger-ui** +- You can use the same swagger properties in the documentation as Spring Boot properties. +**NOTE**: All these properties should be declared with the following prefix: `springdoc.swagger-ui` -### How can i disable/enable Swagger-UI generation based on env variable? +### How can I disable/enable Swagger UI generation based on env variable? - This property helps you disable only the ui. ```properties springdoc.swagger-ui.enabled=false ``` -### How can i hide a parameter from the documentation ? -- You can use @Parameter(hidden = true) +### How can I hide a parameter from the documentation ? +- You can use `@Parameter(hidden = true)` -### Is @Parameters annotation supported ? +### Is `@Parameters` annotation supported ? - Yes -### Does springdoc-openapi supports Jersey? -- If you are using JAX-RS and as implementation Jersey (@Path for example), we do not support it. -- We only support exposing Rest Endpoints using spring managed beans (@RestController for example). +### Does `springdoc-openapi` support Jersey? +- If you are using JAX-RS and as implementation Jersey (`@Path` for example), we do not support it. +- We only support exposing Rest Endpoints using Spring managed beans (`@RestController` for example). - You can have a look at swagger-jaxrs2 project: - [https://github.com/swagger-api/swagger-samples/tree/2.0/java/java-jersey2-minimal](https://github.com/swagger-api/swagger-samples/tree/2.0/java/java-jersey2-minimal). -### Can springdoc-openapi generate API only for @RestController? -- @RestController is equivalent to @Controller + @RequestMapping on the type level. +### Can `springdoc-openapi` generate API only for `@RestController`? +- `@RestController` is equivalent to `@Controller` + `@RequestMapping` on the type level. - For some legacy apps, we are constrained to still support both. -- If you need to hide the @Controller on the type level, in this case, you can use: @Hidden on controller level. -- Please note this annotation can be also used to hide some methods from the generated documentation +- If you need to hide the `@Controller` on the type level, in this case, you can use: `@Hidden` on controller level. +- Please note this annotation can be also used to hide some methods from the generated documentation. -### Are the following validation annotations supported : @NotEmpty @NotBlank @PositiveOrZero @NegativeOrZero ? +### Are the following validation annotations supported : `@NotEmpty` `@NotBlank` `@PositiveOrZero` `@NegativeOrZero`? - Yes -### How can i map Pageable (spring-date-commons) object to correct URL-Parameter in Swagger UI? -The projects that uses spring-data should add this dependency together with the springdoc-openapi-ui dependency: +### How can I map `Pageable` (spring-date-commons) object to correct URL-Parameter in Swagger UI? +The projects that uses `spring-data` should add this dependency together with the `springdoc-openapi-ui` dependency: ```xml org.springdoc @@ -170,8 +168,8 @@ The projects that uses spring-data should add this dependency together with the ``` -### How can i generate enums in the generated description? -- You could add a property allowableValues, to @Parameter. For example +### How can I generate enums in the generated description? +- You could add a property `allowableValues`, to `@Parameter`. For example: ```java @GetMapping("/example") @@ -181,7 +179,7 @@ String json) { } ``` -- or you could override toString on your enum: +- or you could override `toString` on your enum: ```java @Override @@ -191,51 +189,51 @@ public String toString() { } ``` -### Does it really support spring boot 2.2.x.RELEASE & Hateoas 1.0? +### Does it really support Spring Boot 2.2.x.RELEASE & Hateoas 1.0? - Yes -### How can i deploy the Doploy springdoc-openapi-ui, behind a reverse proxy? -- You need to make sure the following header is set in your reverse proxy configuration: X-Forwarded-Prefix -- For example, using apache 2, configuration +### How can I deploy the Doploy `springdoc-openapi-ui`, behind a reverse proxy? +- You need to make sure the following header is set in your reverse proxy configuration: `X-Forwarded-Prefix` +- For example, using Apache 2, configuration: ```properties RequestHeader set X-Forwarded-Prefix "/custom-path" ``` -- Then, in your spring-boot application make sure your application handles this header: X-Forwarded-For. There are two ways to achieve this: +- Then, in your Spring Boot application make sure your application handles this header: `X-Forwarded-For`. There are two ways to achieve this: ```properties server.use-forward-headers=true ``` -- Since spring-boot 2.2, there is a new property to handle reverse proxy headers: +- Since Spring Boot 2.2, there is a new property to handle reverse proxy headers: ```properties server.forward-headers-strategy=framework ``` -- Or you can add the following Bean to your application: +- Or you can add the following bean to your application: ```java @Bean ForwardedHeaderFilter forwardedHeaderFilter() { return new ForwardedHeaderFilter(); } ``` -### How can i control the default expansion setting for the operations and tags, in the swagger-ui , +### How can I control the default expansion setting for the operations and tags, in the Swagger Ui , - You can set this property in your application.yml like so for example: ```properties springdoc.swagger-ui.doc-expansion= none ``` -### Is @JsonView annotations in Spring MVC APIs supported? +### Is `@JsonView` annotations in Spring MVC APIs supported? - Yes -### Adding springdoc-openapi-ui dependency breaks my public/index.html welcome page -- If you already have static content on your root, and you don't want it to be overridden by springdoc-openapi-ui configuration, you can just define a custom configuration of the swagger-ui, in order not to override the configuration of your files from in your context-root: +### Adding `springdoc-openapi-ui` dependency breaks my `public/index.html` welcome page +- If you already have static content on your root, and you don't want it to be overridden by `springdoc-openapi-ui` configuration, you can just define a custom configuration of the `swagger-ui`, in order not to override the configuration of your files from in your context-root: - For example use: ```properties springdoc.swagger-ui.path= /swagger-ui/api-docs.html ``` -### How can i test the Swagger UI? +### How can I test the Swagger UI? - You can have a look on this sample test of the ui: - [https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-ui/src/test/java/test/org/springdoc/ui/app1/SpringDocApp1Test.java](https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-ui/src/test/java/test/org/springdoc/ui/app1/SpringDocApp1Test.java). -### How can i customise the OpenAPI object ? -- You can write your own implementation of OpenApiCustomiser. +### How can I customise the OpenAPI object ? +- You can write your own implementation of `OpenApiCustomiser`. - An example is available on: - [https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app39/SpringDocApp39Test.java](https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app39/SpringDocApp39Test.java). @@ -247,17 +245,17 @@ return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathI } ``` -### How to include spring-boot-actuator endpoints to swagger-ui? -- In order to display spring-boot-actuator endpoints, you will need to add the following property: +### How to include` spring-boot-actuator` endpoints to Swagger Ui? +- In order to display `spring-boot-actuator` endpoints, you will need to add the following property: ```properties springdoc.show-actuator=true ``` -### How can i return an empty content as response? +### How can I return an empty content as response? - It is be possible to handle as return an empty content as response using, one of the following syntaxes: - - content = @content - - content = @content(schema = @Schema(hidden = true)) -- For exemaple: + - `content = @Content` + - `content = @Content(schema = @Schema(hidden = true))` +- For exmaple: ```java @Operation(summary = "Get thing", responses = { @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = String.class))), @@ -269,22 +267,22 @@ ResponseEntity testme() { } ``` -### How are Endpoints with multiple consuming media types supported? +### How are endpoints with multiple consuming media types supported? - An overloaded method on the same class, with the same HTTP Method and path, will have as a result, only one OpenAPI Operation generated. -- In addition, it's recommended to have the @Operation in the level of one of the overloaded methods. Otherwise it might be overriden if its declared many times within the same overloaded method. +- In addition, it's recommended to have the `@Operation` in the level of one of the overloaded methods. Otherwise it might be overridden if it's declared many times within the same overloaded method. -### How can i get yaml and json (OpenAPI) in compile time? -- You can use springdoc-openapi-maven-plugin for this functionnality: +### How can I get yaml and json (OpenAPI) in compile time? +- You can use `springdoc-openapi-maven-plugin` for this functionality: - [https://github.com/springdoc/springdoc-openapi-maven-plugin.git](https://github.com/springdoc/springdoc-openapi-maven-plugin.git). - You can customise the output directory (property outputDir): The default value is: ${project.build.directory} ### What are the ignored types in the documentation? -- Principal, Locale, HttpServletRequest and HttpServletResponse and other injectable parameters supported by Spring MVC are excluded. +- `Principal`, `Locale`, `HttpServletRequest` and `HttpServletResponse` and other injectable parameters supported by Spring MVC are excluded. - Full documentation here: - [https://docs.spring.io/spring/docs/5.1.x/spring-framework-reference/web.html#mvc-ann-arguments](https://docs.spring.io/spring/docs/5.1.x/spring-framework-reference/web.html#mvc-ann-arguments). -### How do i add, authorization header in requests? -- You should add the @SecurityRequirement tags to your protected APIs. +### How do I add authorization header in requests? +- You should add the `@SecurityRequirement` tags to your protected APIs. - For example: ``` @Operation(security = { @SecurityRequirement(name = "bearer-key") }) @@ -299,47 +297,51 @@ ResponseEntity testme() { } ``` -### Differentiation to springfox-project +### Differentiation to Springfox project -- OAS 3 was released in July 2017, and there was no release of springfox to support OAS 3. -springfox covers for the moment only swagger 2 integration with spring-boot. The lastest release date is june 2018. So, in terms of maintenance there is a big lack of support lately. +- OAS 3 was released in July 2017, and there was no release of `springfox` to support OAS 3. +`springfox` covers for the moment only swagger 2 integration with Spring Boot. The lastest release date is june 2018. So, in terms of maintenance there is a big lack of support lately. - We decided to move forward and share the library that we already used on our internal projects, with the community. -- The biggest difference with springfox, is that we integrate new features not covered by springfox: +- The biggest difference with `springfox`, is that we integrate new features not covered by `springfox`: - - The integration between spring-boot and OpenAPI 3 standard. - - We rely on on swagger-annotations and swagger-ui only official libraries. - - We support new features on spring 5, like spring-weblfux with annotated controllers. + - The integration between Spring Boot and OpenAPI 3 standard. + - We rely on on `swagger-annotations` and `swagger-ui` only official libraries. + - We support new features on Spring 5, like `spring-webflux` with annotated controllers. - We do our best to answer all the questions and address all issues or enhancement requests -### How do i migrate to OpenAPI 3 with springdoc-openapi -- There is no relation between springdoc-openapi and springfox.If you want to migrate to OpenAPI 3: +### How do I migrate to OpenAPI 3 with springdoc-openapi +- There is no relation between `springdoc-openapi` and `springfox`.If you want to migrate to OpenAPI 3: - Remove all the dependencies and the related code to springfox - - Add springdoc-openapi-ui dependency + - Add `springdoc-openapi-ui` dependency - If you don't want to serve the ui from your root path or there is a conflict with an existing configuration, you can just change the following property: ```properties springdoc.swagger-ui.path=/you-path/swagger-ui.html ``` -### How can i set a global header? +### How can I set a global header? - You may have global parameters with Standard OpenAPI description. -- You can define common parameters under parameters in the global components section and reference them elsewhere via $ref. You can also define global header parameters. +- You can define common parameters under parameters in the global components section and reference them elsewhere via `$ref`. You can also define global header parameters. - For this, you can override to OpenAPI Bean, and set the global headers or parameters definition on the components level. ```java @Bean public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) { - return new OpenAPI().components(new Components().addSecuritySchemes("basicScheme", - new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")) -.addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1")).addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema()))) -.info(new Info().title("Petstore API").version(appVersion).description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.").termsOfService("http://swagger.io/terms/") -.license(new License().name("Apache 2.0").url("http://springdoc.org"))); - } + return new OpenAPI() + .components(new Components().addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")) + .addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1")).addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema()))) + .info(new Info() + .title("Petstore API") + .version(appVersion) + .description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.") + .termsOfService("http://swagger.io/terms/") + .license(new License().name("Apache 2.0").url("http://springdoc.org"))); +} ``` ### Are Callbacks supported? - Yes -### How can i define SecurityScheme ? -- You can use: @SecurityScheme annotation. +### How can I define SecurityScheme ? +- You can use: `@SecurityScheme` annotation. - Or you can define it programmatically, by overriding OpenAPI Bean: ```java @Bean @@ -352,16 +354,16 @@ public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) { } ``` -### How can i hide an operation or a controller from documentation ? -- You can use @io.swagger.v3.oas.annotations.Hidden annotation at @RestController, @RestControllerAdvice and method level -- The @Hidden annotation on exception handler methods, is considered when building generic (error) responses from ControllerAdvice exception handlers. -- Or use: @Operation(hidden = true) +### How can I hide an operation or a controller from documentation ? +- You can use `@io.swagger.v3.oas.annotations.Hidden` annotation at `@RestController`, `@RestControllerAdvice` and method level +- The `@Hidden` annotation on exception handler methods, is considered when building generic (error) responses from `@ControllerAdvice` exception handlers. +- Or use: `@Operation(hidden = true)` ### How to configure global security schemes? -- For global SecurityScheme, you can add it inisde your own OpenAPI definition: +- For global SecurityScheme, you can add it inside your own OpenAPI definition: ```java @Bean public OpenAPI customOpenAPI() { @@ -376,8 +378,8 @@ public OpenAPI customOpenAPI() { - Generating automatically server url may be useful, if the documentation is not present. - If the server annotations are present, they will be used instead. -###How can i expose the api-docs endpoints without using the swagger-ui? -- You should use the springdoc-openapi-core dependency only: +###How can I expose the api-docs endpoints without using the `swagger-ui`? +- You should use the `springdoc-openapi-core` dependency only: ```xml @@ -386,35 +388,35 @@ public OpenAPI customOpenAPI() { latest.version ``` -### How can i disable springdoc-openapi endpoints ? -- Use the following springdoc property: +### How can I disable `springdoc-openapi` endpoints ? +- Use the following property: ``` springdoc.api-docs.enabled=false ``` -### How can i hide Schema of the the response ? +### How can I hide Schema of the the response ? -- To hide the response element, using @Schema annotation, as follows, at operation level:: +- To hide the response element, using `@Schema` annotation, as follows, at operation level: ``` @Operation(responses = @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true)))) ``` -- Or directly at ApiResponses level: +- Or directly at `@ApiResponses` level: ``` @ApiResponses(value = {@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(hidden = true))) }) OR @ApiResponse(responseCode = "404", description = "Not found", content = @Content) ``` -### What is the url of the swagger-ui, when i set a different context-path? +### What is the url of the `swagger-ui`, when I set a different context-path? - If you use different context-path: ```properties server.servlet.context-path= /foo ``` -- The swagger-ui will be available on the following url: +- The `swagger-ui` will be available on the following url: - http://server:port/foo/swagger-ui.html -### Can i customize OpenAPI object programmatically? +### Can I customize OpenAPI object programmatically? - You can Define your own OpenAPI Bean: ```java @@ -428,28 +430,28 @@ public OpenAPI customOpenAPI(@Value("${springdoc.version}") String appVersion) { } ``` -### Where can i find the source code of the demo applications: +### Where can I find the source code of the demo applications? - The source code of the application is available at the following github repository: - [https://github.com/springdoc/springdoc-openapi-demos.git](https://github.com/springdoc/springdoc-openapi-demos.git). ### Does this library supports annotations from interfaces? - Yes -### What is the list of the excluded parameter types : +### What is the list of the excluded parameter types? - [https://docs.spring.io/spring/docs/5.1.x/spring-framework-reference/web.html#mvc-ann-arguments](https://docs.spring.io/spring/docs/5.1.x/spring-framework-reference/web.html#mvc-ann-arguments). ### Is file upload supported ? -- The library supports the main file types: MultipartFile , @RequestPart, FilePart +- The library supports the main file types: `MultipartFile`, `@RequestPart`, `FilePart` -### Can i use @Parameter inside @Operation annotation ? -- Yes, its supported +### Can I use `@Parameter` inside `@Operation` annotation? +- Yes, it's supported -### Why my parameter is marked as required ? -- Any @GetMapping parameters is marked as required, even if @RequestParam missing. -- You can add @Parameter(required=false) annotation if you need different behaviour -- Query parameters with defaultValue specified are marked as required +### Why my parameter is marked as required? +- Any `@GetMapping` parameters is marked as required, even if `@RequestParam` is missing. +- You can add `@Parameter(required=false)` annotation if you need different behaviour. +- Query parameters with `defaultValue` specified are marked as required. ### How are overloaded methods with the same endpoints, but with different parameters -- springdoc renders these methods as a single endpoint. It detects the overloaded endpoints, and generates parameters.schema.oneOf. +- `springdoc` renders these methods as a single endpoint. It detects the overloaded endpoints, and generates parameters.schema.oneOf. [back](./) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 5bb06585..6d222849 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,25 +5,25 @@ layout: default # **Introduction** -springdoc-openapi java library helps automating the generation of API documentation using spring boot projects. -springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations. +springdoc-openapi java library helps automating the generation of API documentation for Spring Boot projects. +springdoc-openapi works by examining an application at runtime to infer API semantics based on Spring configurations, class structure and various annotations. Automatically generates documentation in JSON/YAML and HTML format APIs. -This documentation can be completed by comments using swagger-api annotations. +This documentation can be completed by comments using `swagger-api` annotations. This library supports: * OpenAPI 3 -* Spring-boot (v1 and v2) +* Spring Boot (v1 and v2) * JSR-303, specifically for @NotNull, @Min, @Max, and @Size. * Swagger-ui * Oauth 2 -This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal) +This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal). # **Getting Started** -## Library for springdoc-openapi integration with spring-boot and swagger-ui -* Automatically deploys swagger-ui to a spring-boot 2 application +## Integration in a Spring Boot project with `swagger-ui` +* Automatically deploys swagger-ui to a Spring Boot 2 application * Documentation will be available in HTML format, using the official [swagger-ui jars](https://github.com/swagger-api/swagger-ui.git). * 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 * server: The server name or IP @@ -39,7 +39,7 @@ This is a community-based project, not maintained by the Spring Framework Contri 1.2.20 ``` -* 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: +* This step is optional: For custom path of the swagger documentation in HTML format, add property in your Spring Boot configuration file: ```properties # swagger-ui custom path @@ -55,13 +55,13 @@ springdoc.swagger-ui.path=/swagger-ui.html ## Source code of the Demo Applications * [https://github.com/springdoc/springdoc-openapi-demos.git](https://github.com/springdoc/springdoc-openapi-demos.git) -## Integration of the libray in a spring-boot 2 project without the swagger-ui: +## Integration of the library in a Spring Boot 2 project without the `swagger-ui`: * Documentation will be available at the following url for json format: http://server:port/context-path/v3/api-docs - * server: The server name or IP - * port: The server port - * context-path: The context path of the application + * `server`: The server name or IP + * `port`: The server port + * `context-path`: The context path of the application * Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yml -* Add the library to the list of your project dependencies. (No additional configuration is needed) +* Add the library to the list of your project dependencies (no additional configuration is needed): ```xml @@ -70,14 +70,14 @@ springdoc.swagger-ui.path=/swagger-ui.html 1.2.20 ``` -* 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: +* This step is optional: For custom path of the OpenAPI documentation in Json format, add property in your Spring Boot configuration file: ```properties # /api-docs endpoint custom path springdoc.api-docs.path=/api-docs ``` -* For wildfly users, you need to add the following dependency to make the swagger-ui work: +* For wildfly users, you need to add the following dependency to make the `swagger-ui` work: ```xml @@ -88,35 +88,35 @@ springdoc.api-docs.path=/api-docs ``` ## Adding API Information and Security documentation - The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info. - These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs. - For better performance of documentation generation, declare @OpenAPIDefinition and @SecurityScheme annotations within a spring managed bean. + The library uses Spring Boot application auto-configured packages to scan for the following annotations in Spring beans: `OpenAPIDefinition` and `Info`. + These annotations declare API Information: Title, version, licence, security, servers, tags, security and externalDocs. + For better performance of documentation generation, declare `@OpenAPIDefinition` and `@SecurityScheme` annotations within a Spring managed bean. -## Error Handling for REST using @ControllerAdvice -To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus +## Error Handling for REST using `@ControllerAdvice` +To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation `@ResponseStatus` -## Disabling the springdoc-openapi endpoints -In order to disable the springdoc-openapi endpoint (/v3/api-docs by default) use the following property: +## Disabling the `springdoc-openapi` endpoints +In order to disable the `springdoc-openapi` endpoint (/v3/api-docs by default) use the following property: ```properties # Disabling the /v3/api-docs enpoint springdoc.api-docs.enabled=false ``` -## Disabling the swagger-ui -In order to disable the swagger-ui, use the following property: +## Disabling the `swagger-ui` +In order to disable the `swagger-ui`, use the following property: ```properties # Disabling the swagger-ui springdoc.swagger-ui.enabled=false ``` ## Swagger-ui configuration -The library supports the swagger-ui official properties: +The library supports the `swagger-ui` official properties: - https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/ -You need to declare swagger-ui properties as spring-boot properties. -All these properties should be declared with the following prefix: **springdoc.swagger-ui** +You need to declare swagger-ui properties as Spring Boot properties. +All these properties should be declared with the following prefix: **`springdoc.swagger-ui`** ## Selecting the Rest Controllers to include in the documentation -Additionally to @Hidden annotation from swagger-annotations, its possible to restrict the generated OpenAPI description using package or path configuration. +Additionally to `@Hidden` annotation from `swagger-annotations`, it's possible to restrict the generated OpenAPI description using package or path configuration. For the list of packages to include, use the following property: ```properties @@ -131,7 +131,7 @@ springdoc.pathsToMatch=/v1, /api/balance/** ``` packages or paths -## Spring-weblfux support with Annotated Controllers +## Spring-webflux support with Annotated Controllers * Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yml * Add the library to the list of your project dependencies (No additional configuration is needed) @@ -142,7 +142,7 @@ packages or paths 1.2.20 ``` -* 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: +* This step is optional: For custom path of the swagger documentation in HTML format, add property in your Spring Boot configuration file: ```properties # swagger-ui custom path @@ -150,8 +150,8 @@ springdoc.swagger-ui.path=/swagger-ui.html ``` ## Spring Pageable support -The support for Pageable of spring-data-commons is available. -The projects that use Pageable type should add this dependency together with the springdoc-openapi-ui dependency. +The support for Pageable of `spring-data-commons` is available. +The projects that use `Pageable` type should add this dependency together with the `springdoc-openapi-ui` dependency. ```xml org.springdoc @@ -161,8 +161,8 @@ The projects that use Pageable type should add this dependency together with the ``` ## Spring security support -For a project that uses spring-security, you should add the following dependency, together with the springdoc-openapi-ui dependency: -This dependency helps ignoring @AuthenticationPrincipal in case its used on REST Controllers. +For a project that uses `spring-security`, you should add the following dependency, together with the `springdoc-openapi-ui` dependency: +This dependency helps ignoring `@AuthenticationPrincipal` in case its used on REST Controllers. ```xml org.springdoc @@ -173,9 +173,9 @@ This dependency helps ignoring @AuthenticationPrincipal in case its used on REST ## **Introduction to springdoc-openapi-maven-plugin** -The aim of springdoc-openapi-maven-plugin is to generate json and yaml OpenAPI description during build time. +The aim of `springdoc-openapi-maven-plugin` is to generate json and yaml OpenAPI description during build time. The plugin works during integration-tests phase, and generate the OpenAPI description. -The plugin works in conjunction with spring-boot-maven plugin. +The plugin works in conjunction with `spring-boot-maven-plugin`. You can test it during the integration tests phase using the maven command: @@ -183,7 +183,7 @@ You can test it during the integration tests phase using the maven command: mvn verify -Dspring.application.admin.enabled=true ``` -In order to use this functionality, you need to add the plugin declaration on the plugins section of your pom.xml: +In order to use this functionality, you need to add the plugin declaration on the plugins section of your `pom.xml`: ```xml @@ -223,12 +223,12 @@ In order to use this functionality, you need to add the plugin declaration on th ## **Custom settings of the springdoc-openapi-maven-plugin** It possible to customise the following plugin properties: -* apiDocsUrl: The local url of your (json or yaml). - * The default value is: http://localhost:8080/v3/api-docs -* outputDir: The output directory, where to generate the OpenAPI description. - * The default value is: ${project.build.directory} -* outputFileName: The file name that contains the OpenAPI description. - * The default value is: openapi.json +* `apiDocsUrl`: The local url of your (json or yaml). + * The default value is: `http://localhost:8080/v3/api-docs` +* `outputDir`: The output directory, where to generate the OpenAPI description. + * The default value is: `${project.build.directory}` +* `outputFileName`: The file name that contains the OpenAPI description. + * The default value is: `openapi.json` ```xml @@ -253,7 +253,7 @@ It possible to customise the following plugin properties: ## Dependencies repository -The springdoc-openapi libraries are hosted on maven central repository. +The `springdoc-openapi` libraries are hosted on Maven Central repository. The artifacts can be viewed accessed at the following locations: Releases: @@ -262,7 +262,7 @@ Releases: Snapshots: * [https://oss.sonatype.org/content/repositories/snapshots/org/springdoc/](https://oss.sonatype.org/content/repositories/snapshots/org/springdoc/). -## spring-weblfux with Functional Endpoints, will be available in the future release +## spring-webflux with Functional Endpoints, will be available in the future release