swagger入门

一.简介

1.什么是 swagger

Swagger 是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用 RESTful Web 服务。尽管大多数用户通过 SwaggerUI 工具识别 Swagger，但是 Swagger 工具集包括对自动文档，代码生成和测试用例生成的支持。

### 2.swagger 特征

1. 通过代码和注释自动生成文档。在 Swagger 框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。方便开发人员在编写代码的同时，编写文档信息。自动生成，只需很少的编辑工作，就能获得完整的 REST APIs 文档
   
2. 提供了 UI 界面。既展示接口信息，又提供了参数校验，测试功能
   
3. 形成了文档规范，支持不同的语言
   
4. 提供丰富的组件。
   

3.依赖包

<!--swagger2-->

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-swagger2</artifactId>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</dependency>

二.使用

1.swagger 注解

swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述 Controller 的作用
  
• @ApiOperation：描述一个类的一个方法，或者说一个接口
  
• @ApiParam：单个参数描述
  
• @ApiModel：用对象来接收参数
  
• @ApiProperty：用对象接收参数时，描述对象的一个字段
  
• @ApiResponse：HTTP 响应其中 1 个描述
  
• @ApiResponses：HTTP 响应整体描述
  
• @ApiIgnore：使用该注解忽略这个 API
  
• @ApiError ：发生错误返回的信息
  
• @ApiParamImplicitL：一个请求参数
  
• @ApiParamsImplicit 多个请求参数
  
• @EnableSwaggerBootstrapUI UI 增强
  
• @ApiOperationSort 接口排序
  
• @ApiSort(value = 5) 给接口排序
  

2.@API

@Api 注解用于标注一个 Controller（Class）。在默认情况下，Swagger-Core 只会扫描解析具有@Api 注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets 等等）的注解。

@Controller

@Slf4j

@RequestMapping("/user")

@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")

public class UserController extends BaseController {

}

3.@ApiOperation

@ApiOperation 注解在用于对一个操作或 HTTP 方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的 HTTP 请求方法及路径组合构成一个唯一操作。

4.@ApiParam

@ApiParam 作用于请求方法上，定义 api 参数的注解。

public ResponseEntity<User> getUserById(

@ApiParam(value = "ID of user that needs to be fetched", allowableValues = "range[1,10]", required = true)

@PathVariable("UserId") Long userId)

5.@ApiResponses

@ApiResponses、@ApiResponse 进行方法返回对象的说明。

@ApiResponses({

 @ApiResponse(code = 200, message = "请求成功"),

 @ApiResponse(code = 400, message = "请求参数没填好"),

 @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")

})

@ResponseBody

@RequestMapping("/user")

public ApiResult getUser(@RequestParam String userId) {

 ...

}

6.@ApiModel

@ApiModel、@ApiModelProperty@ApiModel 用于描述一个 Model 的信息（这种一般用在 post 创建的时候，使用@RequestBody 这样的场景，请求参数无法使用@ApiImplicitParam 注解进行描述的时候）。

@ApiModelProperty 用来描述一个 Model 的属性

使用场景

@ApiModel 用在模型类上,对模型类作注解

@ApiModelProperty 用在属性上,对属性作注解

/**

* <pre>

*     人员信息类

* </pre>

*

*/

@Data

@ApiModel(description= "返回人员信息")

public class UserQueryVo extends BaseEntity{

   @ApiModelProperty(value = "主键", required = true)

   @TableId(value = "id", type = IdType.ID_WORKER)

   private Long id;

   @ApiModelProperty(value = "手机号", required = true)

   private String phonenum;

   @ApiModelProperty(value = "密码", required = true)

   private String password;

   @ApiModelProperty(value = "年龄", required = true)

   private Integer age;

}

7.使用示例

#老版本

<dependency>

   <groupId>com.github.xiaoymin</groupId>

   <artifactId>swagger-bootstrap-ui</artifactId>

   <version>1.9.6</version>

</dependency>

#新版本

<dependency>

   <groupId>com.github.xiaoymin</groupId>

   <artifactId>knife4j-spring-ui</artifactId>

   <version>${lastVersion}</version>

</dependency>

@ApiOperation("信息软删除")

@Api(tags = "任务")

@ApiModelProperty(value = "离线任务数")

@ApiModel(value = "任务统计")  /

8.注解汇总

三.默认链接

1.第一种

#第一种是默认的情况,一般都是这个地址

http://localhost:port/dct-manager/swagger-ui.html

2.第二种

#第二种

http://localhost:8888/swagger/index.html

3.第三种

#第三种

https://beinsight-uat.belle.net.cn/deepexi-dsc-belle-insight/test/command/doc.html

4.WebMvcConfigurer

在WebMvcConfigurer中开始swagger的通行

@Override

public void addResourceHandlers(ResourceHandlerRegistry registry) {

   registry.addResourceHandler("/static/**")

           .addResourceLocations("classpath:/static/");

   registry.addResourceHandler("swagger-ui.html")

           .addResourceLocations("classpath:/META-INF/resources/swagger-ui.html");

   registry.addResourceHandler("/webjars/**")

           .addResourceLocations("classpath:/META-INF/resources/webjars/");

}

四.常见问题

1.请求实例为 null

@ApiModel(value=“测试”)

这个加在类上的注解 value 不能含有特殊符号. 之前为 com.xxxx.xxxx 然后修改掉 . 即可正常显示入参出参

2.版本冲突

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nestedexception is java.lang.NullPointerException

解决方案:

将 SpringBoot 版本降低到 2.6 以下。

五.配置文件

1.配置文件

@Configuration

@EnableSwagger2

public class SwaggerConfig {

   @Bean

   public Docket openapiApiDoc() {

       return new Docket(DocumentationType.SWAGGER_2)

               .groupName("open-api")

               .pathMapping("/")

               .enable(true)

               .apiInfo(apiInfo())

               .select()

               .apis(RequestHandlerSelectors.basePackage("com.xxx"))

               //正则匹配请求路径，并分配到当前项目组

               .paths(PathSelectors.ant("/open-api/**"))

               .build();

   }

   private ApiInfo apiInfo() {

       return new ApiInfoBuilder()

               .title("AI补货预测")

               .description("AI补货预测接口文档")

               .version("v1.0")

               .build();

   }

}

2.pom 文件

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-swagger2</artifactId>

   <version>2.9.2</version>

   <exclusions>

       <exclusion>

           <groupId>io.swagger</groupId>

           <artifactId>swagger-annotations</artifactId>

       </exclusion>

       <exclusion>

           <groupId>io.swagger</groupId>

           <artifactId>swagger-models</artifactId>

       </exclusion>

   </exclusions>

</dependency>

<dependency>

<groupId>io.swagger</groupId>

<artifactId>swagger-annotations</artifactId>

<version>1.5.24</version>

</dependency>

<dependency>

<groupId>io.swagger</groupId>

<artifactId>swagger-models</artifactId>

<version>1.5.24</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.9.2</version>

</dependency>

3.关闭swagger

#关闭swagger

swagger.enabled: false

@Configuration

@EnableSwagger2

public class SwaggerConfig {

   @Value("${swagger.enabled:false}")

   private boolean enabled;

   @Bean

   public Docket openapiApiDoc() {

       return new Docket(DocumentationType.SWAGGER_2)

               .groupName("open-api")

               .pathMapping("/")

               .groupName("11-dsc-11-insight")

               .enable(true)

               .apiInfo(apiInfo())

               .select()

               .apis(RequestHandlerSelectors.basePackage("com.11"))

               //正则匹配请求路径，并分配到当前项目组

               .paths(PathSelectors.ant("/open-api/**"))

               .build()

               .enable(enabled)

               .globalOperationParameters(globalOperationParameters());

   }

   private ApiInfo apiInfo() {

       return new ApiInfoBuilder()

               .title("111")

               .description("111")

               .contact(new Contact("admin", "https://www.11.com", "admin@11.com"))

               .version("v1.0")

               .build();

   }

   private List<Parameter> globalOperationParameters() {

       List<Parameter> parameters = new ArrayList<>();

       parameters.add(new ParameterBuilder()

               .name("rv-token")

               .description("令牌")

               .modelRef(new ModelRef("string")).parameterType("header")

               .required(true)

               .build());

       return parameters;

   }

}