Antes de falar com colegas e algum documento técnico interface deste assunto, e referiu-se a arrogância, o feedback recebido dos estes:
"Um monte de problemas! Interfaces e documentação de código para ser acoplado em conjunto."
"Descrições dos campos para escrever algumas vezes! Uma mudança para mudar um monte de lugares!"
"Parâmetro Request quero descrever claramente escrever um monte de coisas !!"
Eu também parecia sob os métodos de controlo para ser tão descrições de cada parâmetro, fazer um pouco de humanidade ah!
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
E para o valor de retorno, é mais frequentemente exemplo encapsula um objeto de resposta, semelhante a:
@Data
public class RespData{
public static final int Success = 1;
public static final int Error = 0;
private int status;
private Object datas = "";
private Object meta = "";
public RespData(int status, Object datas) {
this.status = status;
if(status == Success){
this.datas = datas;
}else{
this.meta = datas;
}
}
public RespData(Exception e){
this.status = Error;
this.meta = e.getMessage();
}
}
O resultado é finalmente gerado interface de documento, o valor de retorno para esta descrição:
o pessoal de front-end ao ler o documento, ele deve olhar como este direito
Eu provavelmente falar sobre como eles usaram: (não precisa fazer muito trabalho, às vezes, porque eles realmente não familiarizado com a forma como as outras pessoas só vai ver como usar)
Meu ambiente: SpringBoot MyBatis PLUS + 2,1 + 3.1.0 + Swagger2 Lombok
Primeiro de tudo, o mais longe possível na referência usado para transportar objetos, quer obter ou método post, este é um bom hábito, você também pode fazer algum pacote, eu estou aqui para encapsular um PageQuery objetos, há pageno, pageSize dois Integer (em comparação com você Todos os métodos exigem parâmetros de consulta de paginação são colocadas estas duas variáveis para ser elegante e parte dela?)
Então, uma vez que é encapsulado objeto, você pode não ter um grande @ApiImplicitParams fixos de TI! Com este comentário: @ApiModelProperty.
@Data
public class ProductQuery extends PageQuery{
@ApiModelProperty(value = "商品类型ID")
private Long typeId;
}Além de transformar o que são devolvidos dados objetos, suporte para genéricos autorizados
public class RespDataT<T>{
public static final int Success = 1;
public static final int Error = 0;
private int status;
private T datas ;
private Object meta = "";
public RespDataT(T datas) {
this.datas = (T)datas;
this.status =Success;
}
public RespDataT(int status, T datas) {
this.status = status;
if(status == Success){
this.datas =(T) datas;
}else{
this.meta = datas;
}
}
public RespDataT(Exception e){
this.status = Error;
this.meta = e.getMessage();
}
}
Ah, olha como escrever o controlador
@ApiOperation("商品列表")
@GetMapping(path = "/list")
@ResponseBody
public RespDataT<IPage<Product>> list(ProductQuery query) {
try{
Page<Product> page = new Page<>(query.getPage(),query.getPageSize());
IPage<Product> datas = productMapper.getProductPage(page,query);
return new RespDataT<IPage<Product>>(datas);
}catch (Exception e) {
LOGGER.error(e.getMessage(),e);
return new RespDataT<IPage<Product>>(e);
}
}Onde, IPage MyBatis além de parâmetros de paginação é fornecido, o Produto MyBatis mais gerado pela tabela de dados entidade.
Além disso menção de que, MyBatis mais gerador de código, é automaticamente adicionado Swagger2 de anotação! !
GlobalConfig gc = new GlobalConfig();
gc.setSwagger2(true);O código gerado:
Essas entidades geradas foram adicionados @ApiModelProperty, isto é: você acabou de escrever tabelas do banco de anotação, campos, explicar a sua documentação da API também é ok.
Finalmente, olhe para a aparência documento resultante como um Swagger
seção de solicitação contém os parâmetros que herdamos parâmetros de paginação, além de novos atributos de entidade. (Página objetos que eu não adicionar @ApiModelProperty)
E, em seguida, retornar os dados do documento:
ajuste mais tarde encontrou campo, MyBatis além de regenerar código de qual entidade nele.
(De qualquer forma, o código gerado, projetos, tanto quanto possível para não mudar manualmente, e fácil manutenção)
