Swagger 描述API返回信息

一、pom中引入jar

       <swagger2.version>2.8.0</swagger2.version>

        <!--swagger2,API整理工具,通过域名/swagger-ui.html#/可直接访问 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>

二、配置swagger信息

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .globalResponseMessage(RequestMethod.GET,
                        newArrayList(new ResponseMessageBuilder()
                                        .code(500)
                                        .message("系统繁忙！")
                                        .build(),
                                new ResponseMessageBuilder()
                                        .code(200)
                                        .message("请求成功!")
                                        .build()))
                .globalResponseMessage(RequestMethod.POST,
                        newArrayList(new ResponseMessageBuilder()
                                        .code(500)
                                        .message("系统繁忙！")
                                        .build(),
                                new ResponseMessageBuilder()
                                        .code(200)
                                        .message("请求成功!")
                                        .build()))
                .globalResponseMessage(RequestMethod.DELETE,
                        newArrayList(new ResponseMessageBuilder()
                                        .code(500)
                                        .message("系统繁忙！")
                                        .build(),
                                new ResponseMessageBuilder()
                                        .code(200)
                                        .message("请求成功!")
                                        .build()));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API接口文档")
                .description("")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

三、统一返回格式

@ApiModel(value = "返回说明")
public class ResultData<T>{

    @ApiModelProperty(value = "成功标识；true：成功；false:失败")
	private boolean success;

	@ApiModelProperty(value = "返回状态码；200:成功")
	private String code;

	@ApiModelProperty(value = "描述信息")
	private String message;

	private T data;
}

四、controller中使用注解

@Api(value = "登录接口")
public class UserController{
    @ApiOperation(value = "登录", notes = "登录")
    @PostMapping(value = "/doLogin")
    public ResultData<ResultLoginVo> doLogin(LoginAppVo loginAppVo){
            .....
    }
}

五、vo中标注参数信息

@ApiModel
public class LoginAppVo{

    @ApiModelProperty(value="用户名", required = true, dataType = "String")
    private String userName;
    
    @ApiModelProperty(value="用户密码", required = true, dataType = "String")
    private String password;
}

或者，也可以在controller中这样使用：

    @ApiOperation(value = "登录", notes = "返回值：token: 登录成功后的token值，之后的请求请将token放入header中")
    @ApiImplicitParams({@ApiImplicitParam(name = "userName", value = "昵称", required = true, dataType = "String",  paramType="query"),
            @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String",  paramType="query")
    })
    @PostMapping("/doLogin")
    public ResultData doLogin(String userName, String password){
		....
	}

结果：输入图片说明

来源：oschina

链接：https://my.oschina.net/u/2489726/blog/1824309

标签

springfox

swagger

Spring