Swagger2：自动生成API接口文档

Swagger2：自动生成API接口文档

有个项目需要用到Swagger2来做前后端对接，查了下文档发现挺好用的，记录一下

Swagger2使用文档

依赖

<!--swagger2的依赖-->
<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>

配置类

@Configuration
@EnableSwagger2
public class Swagger2Conf {
    @Bean
    public Docket getUserDocket(){
        ApiInfo apiInfo=new ApiInfoBuilder()
                .title("Swagger2演示")//api标题
                .description("API文档")//api描述
                .version("1.0.0")//版本号
                .contact("cyz")//本API负责人的联系信息
                .build();
        return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
                .apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
                .select()//启动用于api选择的构建器
                .apis(RequestHandlerSelectors.basePackage("com.cpaulyz.controller"))//扫描接口的包
                .paths(PathSelectors.any())//路径过滤器（扫描所有路径）
                .build();
    }
}

常用注解

注解	使用的地方	用途
@Api	类/接口	描述类/接口主要用途
@ApiOperation	方法	描述方法的用途
@ApiImplicitParam	方法	用于描述接口的非对象参数
@ApiImplicitParams	方法	用于描述接口的非对象参数集
@ApiIgnore	类/方法/参数	Swagger 文档不会显示拥有该注解的接口
@ApiModel	参数实体类	可设置接口相关实体的描述
@ApiModelProperty	参数实体类属性	可设置实体属性的相关描述
@ApiResponses	方法返回值	用于描述接口的方法返回值
@ApiResponse	方法返回值	用于描述接口的方法返回值集

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

单个参数举例

@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
    //TODO
}

@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

示例

配置实体类

@ApiModel("部门实体类")
@Data
@NoArgsConstructor
@Accessors(chain = true)
public class Dept implements Serializable {
    @ApiModelProperty("ID")
    private int dNo;
    @ApiModelProperty("部门名称")
    private String dName;
    // 这个服务在哪个数据库的字段
    @ApiModelProperty("所属数据库")
    private String dbSource;
}

配置接口类

@Api(tags = "部门管理api")
@RestController
@RequestMapping("/dept")
public class DeptController {

    @Autowired
    DeptService deptService;

    @ApiOperation("添加部门")
    @PostMapping("/add")
    public boolean addDept(Dept dept){
        return deptService.addDept(dept);
    }

    @ApiOperation(value = "根据ID获取部门",notes = "我是notes")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id",value = "部门id",required = true)
    )
    @GetMapping("/get/{id}")
    public Dept get(@PathVariable("id") int id){
        return deptService.queryById(id);
    }

    @ApiOperation("获取全部部门")
    @PostMapping("/getAll")
    public List<Dept> getAll(){
        return deptService.queryAll();
    }


    @Autowired
    DiscoveryClient client;

    @ApiIgnore()
    @GetMapping("/discovery")
    public Object discovery(){
        // 获取微服务列表的清单
        List<String> services = client.getServices();
        System.out.println("discovery=>services:" + services);
        // 得到一个具体的微服务信息,通过具体的微服务id，applicaioinName；
        List<ServiceInstance> instances = client.getInstances("SPRINGCLOUD-PROVIDER-DEPT");
        for (ServiceInstance instance : instances) {
            System.out.println(
                    instance.getHost() + "	" + // 主机名称
                            instance.getPort() + "	" + // 端口号
                            instance.getUri() + "	" + // uri
                            instance.getServiceId() // 服务id
            );
        }
        return this.client;
    }
}

访问UI

http://localhost:xxxx/swagger-ui.html

在webUI上也可以发送请求进行测试，挺好用的

导入postman

import->import from link

之后就可以方便调试了