Spring Boot 集成 Swagger

添加pom 依赖

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

创建Swagger 配置类

@Configuration     // 通过@Configuration注解，让Spring来加载该类配置。
@EnableSwagger2    // 再通过@EnableSwagger2注解来启用Swagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<>();
        pars.add(new ParameterBuilder().name("version").description("版本")
                 .modelRef(new ModelRef("string")).parameterType("header")
                 .required(true).defaultValue("3.5.4").hidden(true).build());
      
        pars.add(new ParameterBuilder().name("platform")
                 .description("平台：1安卓 2：ios")
                 .modelRef(new ModelRef("string")).parameterType("header")
                 .required(true).defaultValue("2").hidden(true).build());

        return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.example.api.*"))
          .paths(PathSelectors.any())
          .build()
          .ignoredParameterTypes(User.class)
          .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("APP_API v3 接口文档")
          .description("更多请关注http://www.baidu.com")
          .termsOfServiceUrl("http://blog.didispace.com/")
          .contact("alevi").version("3.0").build();
    }
}

添加文档内容

@Controller
@RequestMapping("/user")
// 用在类上，说明该类的作用
@Api(value = "UserController", description = "用户相关的Rest接口")
public class UserController extends BaseController {
  
  @ResponseBody
  @RequestMapping(value ="/getUserName", method= RequestMethod.GET)
  // 用在方法上，给API增加方法说明
  @ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1有正确返回")
  @ApiImplicitParams({  // 用在方法上，包含一组参数说明
    // 给方法入参增加说明。 可以多个参数 ，重复配置
    @ApiImplicitParam(name = "userNumber", value = "用户编号", required = true, dataType = "Integer", paramType = "query")
  })
  @ApiResponses(value = {   // 用于表示一组响应
    // 用在@ApiResponses中，一般用于表达一个错误的响应信息
    @ApiResponse(code = 1, message = "Successful — 请求已完成"),
    @ApiResponse(code = 400, message = "请求中有语法问题，或不能满足请求"),
    @ApiResponse(code = 401, message = "未授权客户机访问数据"),
    @ApiResponse(code = 500, message = "服务器不能完成请求")
  })
  public ResultModel getUserName(@RequestParam Integer userNumber){
    if(userNumber == 1){
        ResultModel resultModel = new ResultModel();
        resultModel.status = 1;
        resultModel.message = "";
      	resultModel.data = "张三丰";
      	return resultModel;
    }else{
      	return ResultModel.error(400, "userNumber 不存在");
    }
  }
}

// 描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModel(value = "福利Model", description = "ActivityWelfareListModel")
public class ResultModel<T> implements java.io.Serializable {
	  private static final long serialVersionUID = 1633103597476168895L;
		
    // 描述一个model的属性
    @ApiModelProperty(value = "返回码", required = true)
    private int status;

    @ApiModelProperty(value = "结果描述", required = true)
    private String message;
  
    @ApiModelProperty(value = "数据", required = true)
    private T data;
  
  	public static ResultModel error(int status, String message) {
        ResultModel resultModel = new ResultModel();
        resultModel.status = status.getCode();
        resultModel.message = status.getMessage();
        return resultModel;
    }
}

测试地址： http://localhost:8080/swagger-ui.html

来源：CSDN

作者：Dong滴个Dong

链接：https://blog.csdn.net/justfamily/article/details/104061654

标签

swagger