Swagger 描述API返回信息

1、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>

2、配置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();
    }
}

3、統一返回格式

@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;
}

4、controller中使用註解

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

5、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){
		....
	}

結果：