Swagger documentation details

1、Swagger Introduce

Swagger Is a specification and complete framework , Used to generate 、 describe 、 Invocation and visualization RESTful Style Web service (http
s://swagger.io/). Its main function is ：

1. It makes it more convenient to separate the front end from the back end , It's good for teamwork
2. Documentation of the interface is automatically generated online , Reduce the burden of writing interface documents for back-end developers
3. A functional test Spring Have already put Swagger Include your own criteria , Established Spring-swagger project , Now called Springfox. By means of Introduced in the project Springfox , You can use it very simply and quickly Swagger

2、SpringBoot Integrate Swagger

1. Introduce dependencies

<dependency> 
	<groupId>io.springfox</groupId> 
	<artifactId>springfox-swagger2</artifactId> 
	<version>2.9.2</version> 
</dependency> 
<dependency> 
	<groupId>io.springfox</groupId> 
	<artifactId>springfox-swagger-ui</artifactId> 
	<version>2.9.2</version>
</dependency>

We usually configure it in public projects , Because other microservice projects directly or indirectly depend on

2. Modify the configuration file

   #  Turn on swagger 
   swagger.enable=true

3. In the corresponding project config Add a configuration class to the package

@Configuration
//  And configuration files application.propertis The configuration in corresponds to 
// havingValue  If the value of is equal to the value of the configuration file , Just open swagger
@ConditionalOnProperty(prefix = "swagger",value = {
    "enable"},havingValue = "true")
@EnableSwagger2  // Turn on swagger Annotation support 
public class SwaggerConfiguration {
    

	@Bean
	public Docket buildDocket() {
    
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(buildApiInfo())
				.select()
				//  To scan API(Controller) Basic package 
				.apis(RequestHandlerSelectors.basePackage("cn.ittest.xxx"))
				.paths(PathSelectors.any())
				.build();
	}

	private ApiInfo buildApiInfo() {
    
		Contact contact = new Contact(" The programmer ","","");
		return new ApiInfoBuilder()
				.title(" Development platform - Customer service API file ")
				.description(" Include user services api")
				.contact(contact)
				.version("1.0.0").build();
	}
}

3、Swagger Commonly used annotations

stay Java Class Swagger You can generate Swagger Interface document , Commonly used Swagger The comments are as follows ：

@Api： Decorate the whole class , describe Controller The role of
@ApiOperation： A method that describes a class , Or an interface
@ApiParam： Description information of a single parameter
@ApiModel： Use objects to receive parameters
@ApiModelProperty： When receiving parameters with objects , A field describing an object
@ApiResponse：HTTP In response to 1 Description (s)
@ApiResponses：HTTP Respond to the overall description
@ApiIgnore： Use this annotation to ignore this API
@ApiError ： Information returned in the event of an error
@ApiImplicitParam： A request parameter
@ApiImplicitParams： Description information of multiple request parameters

@ApiImplicitParam attribute ：

We are ConsumerController Add Swagger annotation , The code is as follows ：

@RestController
@Api(value = " Test service Controller", tags = "Consumer", description = " Test service API")
public class ConsumerController {
    

    @ApiOperation(" Test whether I love you ")
    @PostMapping(path = "/love")
    @ApiImplicitParam(name = "name", value = " full name ", required = true, dataType = "String")
    public String hi(String name) {
    
        return " I  love " + name;
    }
}

Access after startup ： http://localhost: Port number / service name /swagger-ui.html
The effect is as follows ：

Swagger Generate API How documents work ：
1、 When the service is started, it will scan SwaggerConfiguration class
2、 The scan package path is specified in this class cn.ittext., You will find the package and sub package marked with @RestController Annotated controller class
3、 according to controller Class Swagger Annotation generation API file