Swagger笔记

Posted 2021-06-26 ITdfq

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Swagger笔记相关的知识，希望对你有一定的参考价值。

引入依赖

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


注意3.0的无法打开swagger-ui.html
<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-swagger-ui</artifactId>-->
<!--            <version>3.0.0</version>-->
<!--        </dependency>-->

注意

开启Swagger2

config

package com.itdfq.springboot_swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author GocChin
 * @Date 2021/6/7 18:22
 * @Blog: itdfq.com
 * @QQ: 909256107
 * @Descript:
 */
@Configuration
@EnableSwagger2 //开启Swagger2
public class Swagger {

}

编写Controller方法

@RestController
public class DemoController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

访问swaagerui

修改默认配置

代码

/**
 * @Author GocChin
 * @Date 2021/6/7 18:22
 * @Blog: itdfq.com
 * @QQ: 909256107
 * @Descript:
 */
@Configuration
@EnableSwagger2 //开启Swagger2
public class Swagger {
    //配置实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(info());
    }
    //配置Swagger信息
    private ApiInfo info(){
        //作者信息
        Contact contact = new Contact("GodChin","http://itdfq.com","909256107@qq.com");
        return new ApiInfo(
                "Swaager日志",
                "学习Swagger2",
                "v1.0",
                "http://itdfq.com",
                contact,"Gitee",
                "https://gitee.com/godchin",
                new ArrayList<>());
    }
}

结果

Swagger扫描接口

代码：

package com.itdfq.springboot_swagger.config;

import com.itdfq.springboot_swagger.controller.DemoController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * @Author GocChin
 * @Date 2021/6/7 18:22
 * @Blog: itdfq.com
 * @QQ: 909256107
 * @Descript:
 */
@Configuration
@EnableSwagger2 //开启Swagger2
public class Swagger {
    //配置实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(info()) //作者
                .select()
                //配置扫描文件路径
                /**
                 * basePackage:指定扫描的包
                 * any（）:扫描全部
                 * none():都不扫描
                 * withClassAnnotation:扫描类上的注解  参数是一个注解的反射对象
                 * withMethodAnnotation:扫描方法上的注解
                 */
//                .apis(RequestHandlerSelectors.basePackage("com.itdfq.springboot_swagger.controller"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.ant("/itdfq/**"))  //过滤什么路径 没有/itdfq/**的就扫描不到了
                .build()
                ;
    }
    //配置Swagger信息
    private ApiInfo info(){
        //作者信息
        Contact contact = new Contact("GodChin","http://itdfq.com","909256107@qq.com");
        return new ApiInfo(
                "Swaager日志",
                "学习Swagger2",
                "v1.0",
                "http://itdfq.com",
                contact,"Gitee",
                "https://gitee.com/godchin",
                new ArrayList<>());
    }
}

结果

扫描结果

配置是否启动Swagger

代码

  public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(info()) //作者
                .enable(false)  //关闭Swagger

                //下面是一套的东西
                .select()
                //配置扫描文件路径
                /**
                 * basePackage:指定扫描的包
                 * any（）:扫描全部
                 * none():都不扫描
                 * withClassAnnotation:扫描类上的注解  参数是一个注解的反射对象
                 * withMethodAnnotation:扫描方法上的注解
                 */
//                .apis(RequestHandlerSelectors.basePackage("com.itdfq.springboot_swagger.controller"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
//                .paths(PathSelectors.ant("/itdfq/**"))  //过滤什么路径 没有/itdfq/**的就扫描不到了
                .build()
                ;
    }

注意事项

注意select下面的扫描是一套，需要再上面开启关闭功能。
结果

多个组配置

代码

 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

结果

配置实体类

实体类代码

@ApiModel("用户类")
public class Users {
    @ApiModelProperty("用户名")
     String username;
    @ApiModelProperty("密码")
     String password;
}

注意：实例类的属性不能是private，私有属性是不会暴露和注释的
结果

常用注解

@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源
```
@Api(tags={"接口"})
@RestController
public class Controller{
}
```
tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息。

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。

@ApiModel(value = "com.biancheng.auth.param.AddUserParam", description = "新增用户")
public class AddUser {
}

@ApiModelProperty() 用于字段，表示对实体类属性的说明。

@Data
@ApiModel(value = "com.itdfq.addUser", description = "新增用户参数")
public class addUser{
    @ApiModelProperty(value = "ID")
    private String id;
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;
}

@ApiParam 用于 Controller 中方法的参数说明。

@PostMapping("/user")
public Users addUser(@ApiParam(value = "新增用户", required = true) @RequestBody AddUser adduser) {
    System.err.println(param.getName());
    return new Users ();
}

value：参数说明
required：是否必填

@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。

@ApiOperation(value="新增用户", notes="详细描述")
public Users addUser(@ApiParam(value = "新增用户", required = true) @RequestBody AddUser param) {

}

value：接口名称
notes：详细说明

@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个@ApiResponse

@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@PostMapping("/user")
public Users addUser(@ApiParam(value = "新增用户", required = true) @RequestBody AddUser addUser) {
}

@ApiImplicitParam 和 @ApiImplicitParams
用于方法上，为单独的请求参数进行说明。
```
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "query", required = true, defaultValue = "1") })
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = Users.class) })
@GetMapping("/user")
public Users getUser(@RequestParam("id") String id) {
    return new Users();
}
```
name：参数名，对应方法中单独的参数名称。
value：参数中文说明。
required：是否必填。
paramType：参数类型，取值为 path、query、body、header、form。
dataType：参数数据类型。
defaultValue：默认值。

以上是关于Swagger笔记的主要内容，如果未能解决你的问题，请参考以下文章

SwaggerUI笔记

Swagger笔记之Swagger注解

Swagger初学习笔记

学习笔记：python3，代码片段（2017）

Swagger笔记

Swagger使用笔记