Swagger2入门

pom文件导入

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

启动类

@SpringBootApplication
@MapperScan("zhangyu.world.plastic.mapper")
@EnableSwagger2
public class PlasticApplication {

	public static void main(String[] args) {
		SpringApplication.run(PlasticApplication.class, args);
	}

}

Configuration

package zhangyu.world.plastic.config.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import zhangyu.world.plastic.anno.MyAnnoSwagger;

import com.google.common.base.Predicates;
import springfox.documentation.builders.RequestHandlerSelectors;

@Configuration
public class SwaggerConfiguration {
    /**
     * 创建 Docket 类型的对象。并使用 spring 容器管理
     * Docket 是 Swagger 中的全局配置对象。
     *
     * @return
     */
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(//配置 swagger 文档主体内容
                        new Contact("章鱼软件—— Tian",//文档的发布者名称
                                "https://zhangyu.world",//文档发布者的网站地址。企业网站
                                "18858442385@163.com")//文档发布者的电子邮箱
                )
                .title("天桥小微企业园")
                .description("Swagger 框架文档详细描述")
                .version("1.1")
                .build();
        //给docket 上下文配置api 描述信息。
        docket.apiInfo(apiInfo);
        docket
                .select() // 获取Docket 中的选择器。返回 ApiSelectorBuilder。构建选择器 的如：扫描什么包的注解
                .apis(
                        Predicates.not(//取反  false -> true  true -> false
                                RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解的时候 返回 true
                                        MyAnnoSwagger.class  //方法上有什么注解的时候返回  true
                                )
                        )
                )
                .apis(RequestHandlerSelectors.basePackage("zhangyu.world.plastic.controller"))//设定扫描哪个包中的注解（包含子包）
                .paths(
                        Predicates.or(//多个规则符合 任意一个即可通过
                                PathSelectors.regex("/swagger/.*"),//使用正则表达式 ， 约束生成api 文档的路径地址
                                PathSelectors.regex("/swagger2/.*")
                        )
                )
                .build();

        return docket;
    }
}

自定义标签

package zhangyu.world.plastic.anno;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @Target - 描述当前的注解可以定义在什么资源上。
 * 属性 value
 *          - 定义具体的资源。 包括：
 *              - ElementType.METHOD 可以定义在方法上
 *              - ElementType.TYPE 可以定义在类型上
 *              - ElementType.TYPE 可以定义在属性上
 *              - ElementType.PARAMETER 可以定义在方法参数上
 * @Retention - 当前注解在什么时候有效
 *  属性 value
 *      - 定义具体的生效标记
 *          -RetentionPolicy.RUNTIME - 运行时有效
 *          -RetentionPolicy.SOURCE - 源码中有效
 *          -RetentionPolicy.CLASS - 字节码有效
 */
@Target(value={ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnoSwagger {
    //自定义注解中的属性 。相当于@MyAnnoSwagger(value="")
    String value() default "";

}

Controller

package zhangyu.world.plastic.controller;

import cn.hutool.http.HttpUtil;
import com.alibaba.fastjson.JSONObject;
import io.swagger.annotations.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import zhangyu.world.plastic.anno.MyAnnoSwagger;
import zhangyu.world.plastic.utils.JsonResult;

/**
 * @Api - 描述当前类型生成帮助文档的信息
 *  属性 -
 *      -tags： 给当前类型定义别名，可以有多个。定义几个别名，在ui 视图中就显示几个控制器访问菜单
 *      - description: 给当前类型生成帮助文档定义一个描述信息
 */
@RestController
@Slf4j
@Api(tags = {"IndexController"})
@RequestMapping("/swagger")
public class IndexController {



   @GetMapping("/test")
//   @ApiImplicitParam(name="m",value = "m参数描述",required = false,paramType ="字符串",dataType = "键值对")
   @ApiImplicitParams(value = {
           @ApiImplicitParam(name="m",value = "m参数描述",required = false,paramType ="字符串",dataType = "键值对"),
           @ApiImplicitParam(name="n",value = "n参数描述",required = true,paramType ="字符串",dataType = "键值对")
   })
   public String test(String m ,String n){
       return  "test";
   }
   @GetMapping("/get")
   //@ApiIgnore 忽略， 当前注解描述的方法或类型，不生产api 帮助文档
   @ApiIgnore
   public String get(String a,String b){
       return "get";
   }
   @MyAnnoSwagger
    @RequestMapping("/req")
    public String req(){
        return "req";
    }
    @PostMapping("/post")
    @ApiOperation(value = "post方法，执行数据新增操作",notes="Swagger学习使用—处理POST方法")
    public String post(
            @ApiParam(name= "用户名（a）",value = "新增用户时提供的用户名",required = true) String a,
            @ApiParam(name= "密码（b）",value = "新增用户时提供的密码",required = true)String b){
        return "post";
    }

   
}

返回Model

package zhangyu.world.plastic.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 *
 */
@Data
@ApiModel(value ="自定义实体-MyEntity",description = "MyEntity存储用户数据")
public class MyEntity implements Serializable {
    @ApiModelProperty(value = "主键",name = "主键（id）",required = false,example = "1",hidden = false)
    private String id;
    @ApiModelProperty(value = "姓名",name = "姓名（name）",required = true,example = "张三",hidden = false)
    private String name;
    @ApiModelProperty(value = "密码",name = "密码（password）",required = true,example = "123456",hidden = false)
    private String password;
}

访问路径 http://localhost:8087/swagger-ui.html