美文网首页从零开始学springboot
24.从零开始学springboot-swagger2文档自动生

24.从零开始学springboot-swagger2文档自动生

作者: 码哥说 | 来源:发表于2019-06-06 14:12 被阅读1次

    前言

    在软件开发周期中,我们写完代码常常还要写文档,一方面给调用方提供调用文档,一方面也能归档。
    其实,做开发的对于写文档这件事很是呵呵,占用了至少40%的开发时间,而且每当代码有调整,还得记得去修改对应的文档。
    那么,springboot有没有哪种方法可以帮助我们自动生成文档呢,这样能解决我们开发人员的痛点。
    本章,我们就来介绍Swagger2这个东东,使用后你会爱上它的。

    好处:

    • 自动生成文档,代码写完,文档即完成
    • 无需复杂的配置,简单易用

    Swagger2常用注解

    @Api()用于类;
    表示标识这个类是swagger的资源

    tags:表示说明
    value:也是说明,可以使用tags替代

    @Api(value="测试controller",tags={"测试接口"})
    @RestController
    public class Swagger2Controller {
    }
    

    @ApiOperation()用于方法;
    表示一个http请求的操作

    value:用于方法描述
    notes: 用于提示内容
    tags: 可以重新分组

    @ApiOperation(value="获取列表",tags={"获取列表信息"},notes="列表")
    @GetMapping("/getList")
    public int getList() {
          return 1;
    }
    

    @ApiParam()用于方法,参数,字段说明;
    表示对参数的添加元数据(说明或是否必填等)

    name:参数名
    value:参数说明
    required:是否必填

    @ApiOperation("查询2")
    @GetMapping("/query")
    public Long query(@ApiParam(name = "id", value = "id", required = true) Long id, @ApiParam(name = "name", value = "名称", required = true) String name) {
            return id;
        }
    

    @ApiModel()用于类
    表示对类进行说明,用于参数用实体类接收
    value:表示对象名
    description:描述

    @ApiModel(value="Person对象",description="用户对象Person")
    public class Person {
    }
    

    @ApiModelProperty()用于方法,字段
    表示对model属性的说明或者数据操作更改
    value:字段说明
    name:重写属性名字
    dataType:重写属性类型
    required:是否必填
    example:举例说明
    hidden:隐藏

    public class Person {
    @ApiModelProperty(value = "名称", name = "name", example = "张三", required = true)
        private String name;
    }
    

    @ApiIgnore()用于类,方法,方法参数
    表示这个方法或者类被忽略

        @ApiIgnore()
        @ApiOperation("隐藏")
        @ApiParam(name = "Person对象", value = "传入json格式", required = true)
        @GetMapping("/hideFunc")
        public Person hideFunc(@RequestBody Person person) {
            return person;
        }
    

    @ApiImplicitParam() 用于方法
    表示单独的请求参数
    name:参数ming
    value:参数说明
    dataType:数据类型
    paramType:参数类型
    example:举例说明

        @ApiOperation("详情")
        @ApiImplicitParam(name = "id", value = "id", required = true, dataType = "long", paramType = "query")
        @GetMapping("/getInfoById")
        public Long getInfoById(Long id) {
            return id;
        }
    

    @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

        @ApiOperation("查询")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "id", dataType = "long", paramType = "query"),
                @ApiImplicitParam(name = "name", value = "名称", dataType = "string", paramType = "query", example = "张三")
        })
        @GetMapping("/queryList")
        public Long queryList(Long id, String name) {
            return id;
        }
    

    更多注解及使用方式请查看

    官方WIKI

    Swagger2配置

    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
    
        //http://127.0.0.1:8080/swagger-ui.html#/
    
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .useDefaultResponseMessages(false)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("swagger自动构建文档")
                    .description("简单使用swagger2")
                    .version("1.0.0")
                    .build();
        }
    }
    

    文档查看地址

    http://127.0.0.1:8080/swagger-ui.html#/

    项目地址

    https://github.com/MrCoderStack/SpringBootDemo/tree/master/sb-swagger2

    请关注我的订阅号

    订阅号.png

    相关文章

      网友评论

        本文标题:24.从零开始学springboot-swagger2文档自动生

        本文链接:https://www.haomeiwen.com/subject/hgqrxctx.html