Springboot+Swagger生成接口文档

首先来说什么是Swagger？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，结合swagger-ui可以动态的生成线上API文档

废话不多说，开始Springboot的整合

第一步，引入依赖

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

第二步，配置swagger配置类

package com.bdcloud.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/***
 * swagger配置类
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("PPP单点定位服务平台ConfigSystem RESTful API")
                //创建人
                .contact(new Contact("lixiangfeng", "http://eip.bdstar.com", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

第三步，配置Models

package com.bdcloud.bean;

import io.swagger.annotations.ApiModel;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
@Table(name = "TB_EMAIL")
@ApiModel(value = "邮件") //注意该注解，其用来标示接口中传递或返回的数据对象
public class Email {

    @Id
    @ApiModelProperty(value="id" ,required=true)
    private  int id;

    private String name;

    private String email;

    private int status;
}

第四步，在Controller中配置Swagger注解

package com.bdcloud.controller;

import com.bdcloud.bean.Email;
import com.bdcloud.response.CommonCode;
import com.bdcloud.response.ResponseResult;
import com.bdcloud.service.EmailService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.io.IOException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Api(description = "邮件模块联系人的增删改查")
@CrossOrigin
@RestController
@RequestMapping("/email")
public class EmailController {

    @Autowired
    EmailService emailService;

    @ApiOperation(value = "查询邮件模块邮箱",notes = "查询邮件所有接收方邮箱")
    @GetMapping("/getAll")
    @CrossOrigin(maxAge = 300)
    public Map getAll(){
        System.out.println("wahah");
        Map<String,Object> result = new HashMap<>();
        List<Email> allEmail = emailService.getAllEmail();
        result.put("code",0);
        result.put("count",allEmail.size());
        result.put("data",allEmail);
        return  result;
    }

    @ApiOperation(value = "根据id查询邮件联系人信息",notes = "查询某个联系人的信息")
    @ApiImplicitParam(name = "id",value = "邮箱id",required = true,paramType = "query",dataType = "int")
    @PostMapping("/getEmailById")
    public Email getEmailById(@RequestParam Integer id){
        return emailService.getEmailById(id);
    }
    
    @ApiOperation(value = "根据id查询邮件联系人信息",notes = "查询某个联系人的信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id",value = "邮箱id",required = true,paramType = "query",dataType = "int")
    })
    @PostMapping(value = "/updateEmail",produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseResult updateEmail(@RequestParam int id,@ApiParam(value = "更新Email对象", required = true) @RequestBody Email email){
        int i = emailService.updateEmail(email);
        ResponseResult result = new ResponseResult();
        if (i!=0){
            return new ResponseResult(CommonCode.SUCCESS);
        }
        return new ResponseResult(CommonCode.FAIL);
    }

}

Swagger文档结果如下：

参数配置小结

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  • paramType：参数放在哪个地方
    • header–>请求参数的获取：@RequestHeader
    • query–>请求参数的获取：@RequestParam
    • path（用于restful接口）–>请求参数的获取：@PathVariable
    • body（不常用）
    • form（不常用）
  • name：参数名
  • dataType：参数类型
  • required：参数是否必须传
  • value：参数的意思
  • defaultValue：参数的默认值
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类
• @ApiModel：描述一个Model的信息
• ,@ApiParam(value = “更新Email对象”, required = true) 可以用来形容一个请求参数需要Object的情况