SpringBoot usa Swagger2
1. Introduce la dependencia de la arrogancia
<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>
2. Agregue la clase de configuración swagger
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//swagger文档扫描的包，这里扫描的是全部
//如果扫描指定包下的可以这样写
//.apis(RequestHandlerSelectors.basePackage("com.xxx.yyy.controller"))
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("标题")
.description("描述")
.version("版本")
.termsOfServiceUrl("公司网址")
.build();
}
}
3. Controlador de prueba
@RestController
@RequestMapping("/test")
public class TestController {
@GetMapping("/test01")
public String test01(){
return "test01";
}
@GetMapping("/test02")
public String test02(){
return "test02";
}
@GetMapping("/test03")
public String test03(){
return "test03";
}
}
4. prueba
Después de que el proyecto se inicia normalmente, el navegador ingresa la URL
http://localhost:8100/swagger-ui.html#/
(el puerto aquí completa el puerto de su propio servicio, el mío es 8100 y el puerto predeterminado es 8080)
Resultados de la prueba
5. Anotación de arrogancia
Lo anterior es el uso básico de swagger
, pero swagger también proporciona algunas anotaciones, aquí hay algunas anotaciones comunes
anotación API
Recurso de documentación utilizado para marcar la clase actual como Swagger. Contiene varios atributos de uso común, que se describen a continuación.
• valor: define el nombre del documento de interfaz actual.
• descripción: se utiliza para definir la descripción del documento de interfaz actual.
@Api(value = "controller接口",description = "用户测试接口")
public class TestController {
Anotación ApiOperationApiOperation anotación
@ApiOperation se usa en el método de la interfaz, principalmente para anotar la interfaz de solicitud. Contiene varios atributos de uso común, que se describen a continuación.
• valor: una breve descripción de la API.
• nota: descripción detallada de la API.
• oculto: si el valor es verdadero, se ocultará en el documento.
manifestación
@GetMapping("/test01")
@ApiOperation(value = "测试方法01",notes = "细节的描述，细节的测试",hidden = false)
public String test01(){
return "test01";
}
ApiImplicitParam, ApiImplicitParams anotaciones
Utilizado en el método de solicitud de API, un subconjunto de @ApiImplicitParams es la anotación @ApiImplicitParam, donde @ApiImplicitParam anota parámetros comunes.
• nombre: El nombre del parámetro.
• valor: valor del parámetro.
• obligatorio: si el valor es verdadero, es un campo obligatorio.
• defaultValue: El valor predeterminado del parámetro.
• dataType: el tipo de datos.
manifestación
@GetMapping("/test02")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "name",value = "测试姓名",required = false,defaultValue = "默认姓名李四"),
@ApiImplicitParam(name = "age",value = "测试年龄",required = false,dataType = "Integer",defaultValue = "200")
})
public String test02(String name,Integer age){
return "test02 姓名："+name+" 年龄:"+age;
}
Anotación ApiParam
ApiParam se utiliza para los parámetros del método, que contiene los siguientes atributos comunes.
• nombre: El nombre del parámetro.
• valor: valor del parámetro.
• obligatorio: si el valor es verdadero, es un campo obligatorio.
• defaultValue: El valor predeterminado del parámetro.
• tipo: el tipo del parámetro.
• oculto: si el valor es verdadero, oculta este parámetro.
Similar a las anotaciones ApiImplicitParam y ApiImplicitParams, no hay más detalles.
ApiResponse, ApiResponses 注解
Tanto @ApiResponses como @ApiResponse se usan juntos para devolver el código de estado HTTP. El valor de @ApiResponses es una colección de @ApiResponse, y varios @ApiResponse están separados por comas. Entre ellos, los parámetros comunes de @ApiResponse son los siguientes.
• código: código de estado HTTP.
• mensaje: información de estado de HTTP.
• responseHeaders: encabezados de respuesta HTTP.
manifestación
@GetMapping("/test03")
@ApiResponses(value = {
@ApiResponse(code = 200,message = "成功"),
@ApiResponse(code = 404,message = "异常")
})
public String test03(){
return "test03";
}
Anotación ResponseHeader
Si necesita configurar el encabezado de respuesta, configure @ResponseHeader en el parámetro responseHeaders de @ApiResponse. @ResponseHeader proporciona los siguientes parámetros.
• nombre: nombre del encabezado de la respuesta.
• descripción: Descripción del encabezado de la respuesta.
ApiModel, ApiModelProperty anotaciones
Establezca la clase de entidad de la respuesta de la API, utilizada como objeto de retorno de la API. Parámetros comunes de @ApiModel.
• valor: nombre de la clase de entidad.
• descripción: descripción de la clase de entidad.
Establezca los atributos de la entidad de respuesta de la API, incluidos los parámetros comunes.
• nombre: nombre del atributo.
• valor: valor del atributo.
manifestación
@ApiModel(value = "Student(学生类)",description = "记录学生个人信息")
public class Student {
public String name;
@ApiModelProperty(name = "age",value = "年龄")
public Integer age;
}
6. Más
El resumen de este artículo es aproximado.
Para un uso más detallado, consulte el sitio web oficial de Swagger