Swagger_Java

简介

swagger是为了协调前后端开发的api文档框架

直接运行，测试api接口支持多种语言支持restful风格 Swagger快速搭建

导入依赖


            io.springfox
            springfox-swagger2
            2.9.2
        

        
            io.springfox
            springfox-swagger-ui
            2.9.2

编写swaggerconfig

@Configuration
//开启swagger
@EnableSwagger2
public class swaggerConfig {
}

测试http://localhost:8080/swagger-ui.html

配置swagger信息

package com.ljk.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;

@Configuration
@EnableOpenApi//开启swagger
public class swaggerconfig {
    //配置swagger的docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger的信息=apiInfo
    public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("学柯君", "www.baidu.com", "sdadads");
        return new ApiInfo("学习日记",
                "对学习的记录",
                "v1.0",
                "www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }
}

## 启动swagger

```java
public class swaggerconfig {
    //配置swagger的docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enable是否启动Swagger，如果为flase则swagger不能再浏览器中使用
    }

如果我们只希望在开发环境中使用，在发布时不使用

@Configuration
@EnableOpenApi//开启swagger
public class swaggerconfig {
    //配置swagger的docket的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles =Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger，如果为flase则swagger不能再浏览器中使用
    }

创建多个swagger日志

package com.ljk.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;

@Configuration
@EnableOpenApi//开启swagger
public class swaggerconfig {
    @Bean
    public Docket docket1(){
        return new Docket(documentationType.SWAGGER_2).groupName("DDD");
    }
    @Bean
    public Docket docket2(){
        return new Docket(documentationType.SWAGGER_2).groupName("DD2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(documentationType.SWAGGER_2).groupName("D");
    }

    //配置swagger的docket的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles =Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(documentationType.SWAGGER_2).groupName("学柯君")
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger，如果为flase则swagger不能再浏览器中使用
                .select()
                //RequestHandlerSelectors:配置要扫描接口的方式
                //basePackage:指定要扫描的包
                    //any():扫描全部
                    //none:不扫描
                    //withClassAnnotation
//                   withMethodAnnotation
                .apis(RequestHandlerSelectors.basePackage("com.ljk.controller"))
                //过滤什么路径
                .paths(PathSelectors.ant("/ljk/**"))
                .build();
    }
    //配置Swagger的信息=apiInfo
    public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("学柯君", "www.baidu.com", "sdadads");
        return new ApiInfo("学习日记",
                "对学习的记录",
                "v1.0",
                "www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }
}

swagger配置扫描接口

实体类

package com.ljk.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api(注释)
@ApiModel("用户类")
public class user {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("用户密码")
    public String pwd;
}

controller

package com.ljk.controller;

import com.ljk.pojo.user;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class helloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello swagger";
    }
    //只要我们的接口中，返回值中存在实体类，它就会被扫描到swagger中
    @PostMapping("/user")
    public user user(){
        return new user();
    }
    //Operation接口，不是放在类上的，是方法
    @ApiOperation("hello控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String name){
        return "hello"+name;
    }
    //Operation接口，不是放在类上的，是方法
    @ApiOperation("post测试方法")
    @GetMapping("/postt")
    public user postt(@ApiParam("类") user user){
        return user;
    }
}

总结

我们可以通过swagger给一些比较难理解的属性和接口，增加注释接口文档实时更新可以在线测试

注意：发布项目是一定关闭

常用注解

@Api():

作用：Api该注解用在类上标记一个Controller类作为文档源属性：tags表示接口说明，可以多配置语法格式：

@Api(tags={"类名"})

实例：

//Api该注解用在类上标记一个Controller类作为文档源
//tags表示接口说明，可以多配置
@Api(tags = {"用户接口"})
@RestController
public class test {
    @RequestMapping("/hello")
    public String hello(){
        return "HELLO";
    }
}

结果：

@ApiModel

作用：该注解用在类上，表示对类进行说明，用于实体类的参数接受说明

属性：

value：类所在的包description ：对类的作用描述

实例

@ApiModel(value = "com.swaggertest.entity.User",description = "用户类")
public class User {
    private int id;
    private String name;
    private String phone;
    private String address;
    private String age;
}

@ApiModelProperty

作用：用于字段，表示对 model 属性的说明

实例：

@ApiModel(value = "com.swaggertest.entity.User",description = "用户类")
public class User {
    //@ApiModelProperty() 用于字段，表示对 model 属性的说明
    @ApiModelProperty(value = "ID")
    private int id;
    @ApiModelProperty(value = "名字")
    private String name;
    @ApiModelProperty(value = "手机")
    private String phone;
    @ApiModelProperty(value = "地址")
    private String address;
    @ApiModelProperty(value = "年龄")
    private String age;

}

结果

@ApiParam

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

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

实例

  @RequestMapping("/getUer")
    public User getUser(@ApiParam(value = "新增用户参数" ,required = true) User user){
        return new User(1,"sda","sda","sda","sad");
    }

@ApiOperation

作用：@ApiOperation，用在Controller里的方法上，说明方法的作用

属性：

value接口名称notes：详细说明

实例

@RequestMapping("/getUer")
    @ApiOperation(value = "得到用户",notes = "详细描述")
    public User getUser(@ApiParam(value = "新增用户参数" ,required = true) User user){
        return new User(1,"sda","sda","sda","sad");
    }

结果：

ApiResponse 和 ApiResponses

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

实例：

@ApiResponses({@ApiResponse(code = 200,message = "ok",response = User.class)})
 @RequestMapping("/getUer")
 @ApiOperation(value = "得到用户",notes = "详细描述")
 public User getUser(@ApiParam(value = "新增用户参数" ,required = true) User user){
     return new User(1,"sda","sda","sda","sad");
 }

ApiImplicitParam 和 ApiImplicitParams

作用：用于方法上，为单独的请求参数进行说明

属性

name：参数名，对应方法中单独的参数名称。value：参数中文说明。required：是否必填。paramType：参数类型，取值为 path、query、body、header、form。dataType：参数数据类型。defaultValue：默认值。

实例

    @ApiImplicitParams({@ApiImplicitParam(name = "id",value = "用户ID",dataType = "STRING")})

Swagger

Java相关栏目本月热门文章