简介

Swagger是一种接口描述语言，用于描述使用JSON表示的RESTful API。

Swagger与一组开源工具一起使用，以设计，构建，记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

说人话：

没写项目前把接口文档写好，文档中要把前后端的接口规则定义好，大家照着这些规则去开发接口

快速入门

依赖

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
   <version>3.0.0</version>
</dependency>

配置

如果使用2.5.10以上版本，请加如下配置

spring.mvc.pathmatch.matching-strategy=ant_path_matcher      # path_pattern_parser

注解

@SpringBootApplication
@EnableOpenApi
public class SpringbootdemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootdemoApplication.class, args);
    }
}

地址

http://localhost:8080/swagger-ui/index.html

结果

@RestController
public class PersonController {

    @GetMapping("/findList")
    public  Map<String,Object>  findList() {
        HashMap<String, Object> hashMap = new HashMap<>();
        hashMap.put("code",200);
        hashMap.put("message","ok");
        hashMap.put("data",null);
        return hashMap;
    }
}

注解

@Api

用在Controller层上的，表示对类的说明，tags="说明该类的作用，可以在UI界面上看到的注解"，description是具体描述

@RestController
@Api(tags = "人",description="与人相关的操作")
public class PersonController {
  .....
}

@ApiOperation

• 用在请求的方法上，说明方法的用途、作用

• value="说明方法的用途、作用"

• notes="方法的备注说明"

• hidden=true UI界面上隐藏该接口

• @ApiOperation(value = "查询所有人的数据",notes = "不需要传参")
    @GetMapping("/findList")
      public  Map<String,Object>  findList() {
          HashMap<String, Object> hashMap = new HashMap<>();
          hashMap.put("code",200);
          hashMap.put("message","ok");
          hashMap.put("data",null);
          return hashMap;
      }

@ApiImplicitParams

• @ApiImplicitParams：用在请求的方法上，表示一组参数说明

• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• name：参数名，不能为null

• value：参数的汉字说明、解释

• required：参数是否必须传

• defaultValue：参数的默认值

@ApiOperation(value = "根据id查询具体人的信息")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "1")
    @GetMapping("/findById")
    public  Map<String,Object>  findById(Integer id) {
        HashMap<String, Object> hashMap = new HashMap<>();
        hashMap.put("code",200);
        hashMap.put("message","ok");
        hashMap.put("data",null);
        return hashMap;
    }  

	
    @ApiOperation(value = "分页查询人的信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum",value = "请求页数",required = true,defaultValue = "1"),
            @ApiImplicitParam(name = "pageSIze",value = "请求条数",required = true,defaultValue = "10")
    })
    @GetMapping("/findByPage")
    public  Map<String,Object>  findById(Integer pageNum,Integer pageSize) {
        HashMap<String, Object> hashMap = new HashMap<>();
        hashMap.put("code",200);
        hashMap.put("message","ok");
        hashMap.put("data",null);
        return hashMap;
    }

@ApiModel

• 用于响应类上，表示一个返回响应数据的信息

• 这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候

• value：标注实体是做什么的

• description：描述信息，内容可以在UI界面显示出来

@ApiModelProperty

用在属性上，描述响应类的属性

value：信息描述，内容可以在UI界面显示出来

required：必填值

hidden：可以在UI界面上隐藏不显示，比如一些is_deleted这些前端是不需要传递的

@ApiOperation(value = "根据id修改人的信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "1")
    })
    @PostMapping("/updateById")
    public  Map<String,Object>  updateById(Integer id, @RequestBody Person person) {
        HashMap<String, Object> hashMap = new HashMap<>();
        hashMap.put("code",200);
        hashMap.put("message","ok");
        hashMap.put("data",null);
        return hashMap;
    }

@Data
@ApiModel("人")
public class Person {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty(value = "用户姓名",required = true)
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;
    @ApiModelProperty(value = "密码",hidden = true)
    private String password;
}

knife4j

概述

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案

他是对原生的swagger进行了封装

Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j

依赖

以前的springfox-boot-starter就不需要了，直接引入如下依赖即可

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

测试地址

http://localhost:8080/doc.html#/home

配置代码

package com.codingfuture.swagger_demo.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author Petrel
 */
@Configuration
//@EnableSwagger
public class ConfigSwagger {
    public class Swagger2 {

        //默认文档地址为 http://localhost:8088/swagger-ui.html
        //新接口文档地址为 http://localhost:8080/doc.html#/home
        @Bean
        public Docket createRestApi(){

            return new Docket(DocumentationType.SWAGGER_2)          //指定Api类型为Swagger2
                    .apiInfo(apiInfo())                             //指定文档汇总信息
                    .select()
                    .apis(RequestHandlerSelectors.any()) //          或者指定controller包路径
                    .paths(PathSelectors.any())                      //指定展示所有controller
                    .build();
        }

        private ApiInfo apiInfo(){
            //返回一个apiinfo
            return new ApiInfoBuilder()
                    .title("api接口文档")                               //文档页标题
                    .contact(new Contact( "Petrel",
                            "https://www.123.com",
                            "123@sina.com"))                                  // 联系人信息
                    .description("简介")                            // 详细信息
                    .version("1.0.1")                                  // 文档版本号
                    .termsOfServiceUrl("https://www.123.com")                      //网站地址
                    .build();
        }

    }
}