swagger入门

关联知识

postman

一个测试接口的工具。

快速开始

入门案例

0. 创建一个spring web项目；

1. 导入依赖

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>  
   </dependency>
   

2. 新建一个controller类

   @RestController
   public class HelloController {
   ​
       @RequestMapping(value = "/hello")
       public String hello(){
           return "hello000swagger!";
       }
   }
   

3. 添加swagger配置类，可以在此类中修改页面的默认配置。

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   ​
   }
   

4. 启动springboot项目，浏览器地址栏输入http://localhost:8080/swagger-ui.html，即可看到默认的ui页面

5. 配置分组扫描

     @Bean
       public Docket docket1() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apinfo1())
                   .enable(true)  //是否开启swagger
                   .groupName("docket1") 
                   .select()
                   //指定某个分组所扫描的包，完成协同开发，前者指定扫描接口方式，后者指定包路径。
                   .apis(RequestHandlerSelectors.basePackage("com.vlog.swagger.controller"))
                   .build()
                   .path();  //过滤指定包下的路径
       }
   

   • 为不同的生产设置是否开启swagger

     ​
     @Bean
         public Docket docket1(Environment environment) {
         //        设置要显示的swagger环境
         Profiles profiles = Profiles.of("dev");
         //    判断是否处于增加设定的环境中
         boolean flag = environment.acceptsProfiles(profiles);
         //   将flag传入enable方法即可  
         ……
         
         }
       
     

6. 增加注释

   • 实体类@ApiModel(value="用户实体类") <= 需要有返回该实体类的方法才生效。

   • 实体类属性@ApiModelProperty(value="用户姓名")

   • 控制类方法@ApiOperation(value="返回实体类"，notes="完善中"）

   • 控制类@Api(tag="控制类"）

   • 参数@ApiImplicitParams/@ApiImplicitParam，用法如下：

//@ApiImplicitParams用法
@ApiImplicitParams(value = {
        @ApiImplicitParam( name = "name",value = "传进来的用户名",required = true),
        @ApiImplicitParam( name = "psw",value = "传进来的用户密码",required = true)
})
//@ApiImplicitParam用法
 @ApiImplicitParam( name = "psw",value = "传进来的用户密码",required = true)

注意事项

1. 如果输入ui地址显示 Whitelabel Error Page，检查一下依赖有没有正确导入，该ui页面存在swagger-ui.jar包中，如图所示：

补充

自定义注解

/**
 * @author Zonda
 * 该注解可以定义在ElementType.TYPE（类型）、field(属性)
 */
@Target(value = {ElementType.METHOD,ElementType.TYPE})
//规定起效作用域
@Retention(RetentionPolicy.RUNTIME) 
public @interface MyAnnotationSwagger {
        String value() default "";
}