This is the fourth day of my participation in the August More text Challenge. For details, see: August More Text Challenge

Introduction of Swagger

Swagger Swagger is a framework for easy API development that has the following advantages:

  • Automatically generate online documentation, back-end developer changes can be immediately reflected in the online documentation, and do not have to write separate interface documentation, reducing the development burden
  • Supported bySwaggerPage direct debugging interface, convenient front-end developers for testing

Configuration Swagger

Swagger is currently available in two major versions, 2.x and 3.x, in slightly different configurations.

  1. Add the dependent

Swagger is a technology that follows the OpenAPI specification, and Springfox is an implementation of that technology, so search springfox instead of Swagger.

  • forSwagger 2.xThat need to be inpom.xmlTo add two configurations:
<! -- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> < artifactId > springfox - swagger2 < / artifactId > < version > 2.9.2 < / version > < / dependency > <! -- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> < artifactId > springfox swagger - UI < / artifactId > < version > 2.9.2 < / version > < / dependency >Copy the code
  • forSwagger 3.x, simplifies the configuration items needed only inpom.xmlTo add a configuration:
<! -- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter --> <dependency> < the groupId > IO. Springfox < / groupId > < artifactId > springfox - the boot - starter < / artifactId > < version > 3.0.0 < / version > < / dependency >Copy the code
  1. Start for a projectSwagger
  • forSwagger 2.x, the use of@EnableSwagger2Annotations to openSwaggerFunction.
@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
    ...
}
Copy the code
  • forSwagger 3.x, the use of@EnableOpenApiAnnotations to openSwaggerFunction.
@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
    ...
}
Copy the code
  1. createSwaggerConfigThe configuration class
  • forSwagger 2.xTo instantiateDocketWe need to pass it inDocumentationType.SWAGGER_2.
  • forSwagger 3.xTo instantiateDocketWe need to pass it inDocumentationType.OAS_30.

Here is a configuration template:

import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class SwaggerConfig { @Value("${spring.profiles.active:NA}") private String active; @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // OAS_30 Swagger.apiinfo (apiInfo()).host("http://www.example.com") // Base URL only in the development environment .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo ApiInfo () {return new ApiInfoBuilder().title("API document ").description(" this is the description ").contact(new) Contact (" zhang ", null, null)) version (" 1.0 "). The build (); }}Copy the code
  1. accessSwaggerThe front page
  • forSwagger 2.xTo accesshttp://localhost:8080/swagger-ui.html
  • forSwagger 3.xTo accesshttp://localhost:8080/swagger-ui/

Controller related notes

  • @Api: marks a class asSwaggerResources, generally put inControllerClass above, throughtagsSpecify the description, such as@api (tags=" User management ").
  • @ApiOperation: This note is placed inControllerMethod above, describes what the method does.
  • @ApiParam: This note is placed inControllerBefore the parameter of a method, you can describe what the parameter does, such as@apiparam (" username ") String username. You can usevalueTo specify the description, passrequired = trueSpecifies that this parameter must be passed.
package com.example.swagger.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @api (tags = "Hello controller ") @RestController public Class HelloController {@apiOperation (" Welcome message ") @getMapping ("/ Hello ") Public String hello(@apiparam (" name ") String name) {return "hello, "+ name; }}Copy the code

Entity related annotations

  • @ApiModel: is usually placed on top of an entity class. Can be achieved byvalueSpecifies an alias. If not specified, the class name defaults. You can also go throughdescriptionSpecify detailed description. Such as@ ApiModel (" user ")Will showThe userRather thanUser.

! [] (cdn.jsdelivr.net/gh/jpch89/P… Use Swagger 00.png in Spring Boot)

If you want to specify only the description without changing the original class name display, you can write @apiModel (Description = “user “).

  • @ApiModelProperty: is usually placed on the member variable of the entity classvalueSpecify the description,exampleSpecify sample data,required = trueSpecifies that this parameter is required,hidden = trueUsed to hide the field, not inAPIDisplayed in the document.
package com.example.swagger.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @data @apiModel (description = "User ") public class User {@apiModelProperty (" User ") private String username; @data @apiModel (description =" User ") public class User {@apiModelProperty (" User ") private String username; @apiModelProperty (" password ") private String password; @apiModelProperty (value = "age ", example = "18", required = true) private int age; @ApiModelProperty(hidden = true) private double money; }Copy the code

2021.08.04