swagger教学嵌入Spring Boot项目中使用教程

pom文件引入

        <!--swagger3-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        
        
        
        或者
        
         <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>

创建一个swagger的配置类

@Configuration
@EnableOpenApi
@ConditionalOnProperty(prefix = "knife4j",name = "enable",havingValue = "true")//在application.yml文件中配置
public class Swagger2Config {

    @Bean
    public Docket restApi() {

 // DocumentationType.SWAGGER_2 固定的，代表swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())// 用于生成API信息
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()// select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xx"))// 用于指定扫描哪个包下的接口
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX项目API")// 可以用来自定义API的主标题
                .description("XX项目SwaggerAPI管理")// 可以用来描述整体的API
                .contact(new Contact("Fisher", "https://blog.csdn.net/qq_40977118", "xxx@163.com"))// 用于定义服务的域名
                .version("1.0")
                .build();
    }

定义接口

@Api(tags = "角色管理") // tags：你可以当作是这个组的名字。 @RestController public class RoleController { }

对于GET方式，swagger不推荐使用body方式来传递数据，也就是不希望在GET方式时使用json、form-data等方式来传递，这时候最好使用路径参数或者url参数。(😓虽然POSTMAN等是支持的)，所以如果接口传递的数据是json或者form-data方式的，还是使用POST方式好。

场景一：请求参数是实体类。

此时我们需要使用@ApiModel来标注实体类，然后在接口中定义入参为实体类即可：

• @ApiModel：用来标类

  • 常用配置项：

    • value：实体类简称

    • description：实体类说明

• @ApiModelProperty：用来描述类的字段的意义。

  • 常用配置项：

    • value：字段说明

    • example：设置请求示例（Example Value）的默认值，如果不配置，当字段为string的时候，此时请求示例中默认值为"".

    • name：用新的字段名来替代旧的字段名。

    • allowableValues：限制值得范围，例如{1,2,3}代表只能取这三个值；[1,5]代表取1到5的值；(1,5)代表1到5的值，不包括1和5；还可以使用infinity或-infinity来无限值，比如[1, infinity]代表最小值为1，最大值无穷大。

    • required：标记字段是否必填，默认是false,

    • hidden：用来隐藏字段，默认是false，如果要隐藏需要使用true，因为字段默认都会显示，就算没有@ApiModelProperty。

// 先使用@ApiModel来标注类
@ApiModel(value="用户登录表单对象",description="用户登录表单对象")
public class LoginForm {
    // 使用ApiModelProperty来标注字段属性。
    @ApiModelProperty(value = "用户名",required = true,example = "root")
    private String username;
    @ApiModelProperty(value = "密码",required = true,example = "123456")
    private String password;

    // 此处省略入参赋值时需要的getter,setter,swagger也需要这个
}

定义成入参：

@ApiOperation(value = "登录接口",notes = "登录接口的说明")
    @PostMapping("/login")
    public LoginForm login(@RequestBody LoginForm loginForm){
        return loginForm;
    }

不过我一般都是用于实体类
 

@TableName("goods_type")
@ApiModel(value = "商品类别实体")
public class GoodsType {

具体详情还是根据项目实际想布局多少而定
可以参考下https://www.cnblogs.com/progor/p/13297904.html