swagger使用

末蓝、 2022-02-25 16:18 285阅读 0赞

依赖

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

配置

package com.study.swagger.config;
    
    
    import io.swagger.annotations.Api;
    import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.ParameterBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.schema.ModelRef;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    import java.util.List;
    
    /**
     * @author: 李坡
     * @date: 2019/1/17 10:08
     */
    @Configuration
    @EnableSwagger2
    @ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
    public class Swagger2 {
        @Bean
        public Docket createRestApi() {
            ParameterBuilder tokenPar = new ParameterBuilder();
            List<Parameter> pars = new ArrayList<>();
            tokenPar.name("token")
                    .description("令牌")
                    .modelRef(new ModelRef("string"))
                    .parameterType("query")
                    .required(false);
            pars.add(tokenPar.build());
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //.apis(RequestHandlerSelectors.basePackage("com.sst"))
                    // 这里是全局扫描有@Api注解得类，还可以扫描任意位置，指定包以及针对方法上的指定注解
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    .paths(PathSelectors.any())
                    .build()
                    .globalOperationParameters(pars);
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("个人测试")
                    .description("个人测试用api")
                    .termsOfServiceUrl("")
                    .contact("测试")
                    .version("1.0")
                    .build();
        }
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 1]

controller

package com.study.swagger.controller;
    
    import com.study.swagger.model.BaseForm;
    import com.study.swagger.model.GetForm;
    import com.study.swagger.model.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    /**
     * @author: 李坡
     * @date: 2019/1/17 12:00
     */
    @RestController
    @RequestMapping("/user")
    @Api(value = "用户Controller", tags = {"用户", "测试", "Controller"})
    public class UserController {
    
        @ApiOperation(value = "查询用户", notes = "查询用户", httpMethod = "POST")
        @RequestMapping(value = "/getByForm")
        //返回值不能是Object，否则，swagger返回不显示。
        //Result具体化泛型，swagger就显示具体类
        //swagger根据方法的返回值显示，与具体的返回结果无关
        public Result<PageVO<User>> getByForm(GetForm form){
            User u = new User(form.getName(), form.getAge());
            List<User> list = new ArrayList<>();
            list.add(u);
            //return Result.ok(u);//swagger显示
            //return Result.ok(list);//swagger也显示
            PageVO<User> pageVO = new PageVO<>(10, list);
            return Result.ok(pageVO);//swagger也显示。
        }
    
    }

实体类  
入参

package com.study.swagger.model;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    import java.util.List;
    
    /**
     * 基础表单.
     *
     * @author <a href="mailto:simonzbf@163.com">大兵</a>
     * @version 1.0 18/4/24
     * @since 1.0
     */
    @Data
    @ApiModel//只需要子类添加这个注解，父类不需要添加这个注解
    public class GetForm extends BaseForm {
        @ApiModelProperty("姓名")
        private String name;
    
        @ApiModelProperty("年龄")
        private Integer age;
    
    }
    
    @Data
    public class BaseForm {
    
        @ApiModelProperty("请求id")
        private String requestId;
    
        private Boolean excel;
    
    }

package com.study.swagger.model;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    /**
     * Created by e-lipo on 2019/4/2.
     */
    @Data
    @ApiModel
    @AllArgsConstructor
    @NoArgsConstructor
    public class User {
        @ApiModelProperty("姓名")
        private String name;
    
        @ApiModelProperty("年龄")
        private Integer age;
    }

package com.study.swagger.model;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    import java.io.Serializable;
    
    /**
     * @author zhangqi
     * @date 2019/3/25 8:54 AM
     */
    @Data
    @NoArgsConstructor
    @ApiModel
    public class Result<T> implements Serializable {
    
        @ApiModelProperty("数据")
        T data;
    
        @ApiModelProperty("提示信息")
        String message;
    
        @ApiModelProperty("状态码")
        Integer code;
        
        public Result(Integer code, String message){
            this.code = code;
            this.message = message;
        }
    
        public Result(Integer code, String message, T data){
            this.data = data;
            this.code = code;
            this.message = message;
        }
    
        public static <T> Result ok(T data){
            return new Result(0, "成功", data);
        }
    
    }

package com.study.swagger.model;
    
    import io.swagger.annotations.ApiModelProperty;
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    import java.util.List;
    
    /**
     * Created by e-lipo on 2019/4/2.
     */
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class PageVO<T> {
        @ApiModelProperty("总记录数")
        private long total;
    
        @ApiModelProperty("数据集合")
        private List<T> list;
    }

启动成功后，访问  
[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 2]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 3]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 4]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70]: /images/20220225/cf0b36052aea4c8ca57dd36049e630f3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 1]: /images/20220225/7a5c7e9aac634bb6a4740a4873d77424.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 2]: /images/20220225/a9f99f56c3e741d6bbb5c63ab1156344.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 3]: /images/20220225/605aad8c8d114589a9342302dbd8ba1e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L21pbmd3dWxpcG8_size_16_color_FFFFFF_t_70 4]: /images/20220225/9bae249ca9ea435bbef7e26ee8372f3e.png