如何快速的用用一个小时来学习swagger？从搭建springboot+swagger

新建一个springboot项目

加入相关依赖

        <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>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

编写一个hello工程

测试运行

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

配置swagger

package com.zhang.config;



@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
   
    //配置swagger的docket实列
    @Bean
    public Docket docket(){   
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
              
    }
    //配置swagger信息，apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("小张同学","https://blog.youkuaiyun.com/qq_45621392","dreamzxj@qq.com");
        return new ApiInfo(
                "小张同学的开发文档",
                "即使在小的帆也能远航",
                "v1.0",
                "https://blog.youkuaiyun.com/qq_45621392",
                contact,
                "Apache 2.0",
                "http: //www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

配置扫描接口及开关

配置是否启动swagger

设置为false启动项目，发现swagger不能展示

让swagger扫描不一样的环境

Swaggerconfig.java下添加如下

在创建application.properties文件的生成环境和发布环境，分别给生成和发布环境不一样的端口号，在通过application.properties文件激活选择使用哪个环境




在swaggerconfig.java下通过一下获取配置文件

 //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev");
         //通过environment.acceptsProfiles来判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
		return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)  //enable是否启动swagger，如果为false,则在浏览器中不能使用

启动项目，此时在application.properties文件配置文件已经激活dev开发环境

//激活开发环境
	spring.profiles.active=dev

此时在浏览器能正常访问swagger

修改application.properties文件配置文件的环境为生产环境pro时，并且swaggerconfig.java中读取配置文件并没有修改为pro,此时浏览器上不能访问swagger

application.properties:
		spring.profiles.active=pro

swaggerconfig.java
  //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev");

启动项目，通过8082端口访问，目前的8082端口被占用上面截图就不能及时更换，此时通过8082端口访问，发现swagger是不能访问的

配置Api文档的分组

   .groupName("小张")

如何配置多个分组;多个Docket实例即可

  //配置多个分组，实现多个docket实列即可
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("小王");
    }
    @Bean

    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("张三");
    }
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
    }

实体类配置

创建实体类

package com.zhang.domain;

public class User {
    public String username;
    public String pwd;
}

编写接口

 @GetMapping("/user")
    public User user() {
        return new User();
    }

启动项目

给文档添加注释--------实体类

给文档添加注释-------接口

启动项目·

总结

pom.xml

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

SwaggerConfig.java

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
    //配置多个分组，实现多个docket实列即可
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("小王");
    }
    @Bean

    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("张三");
    }
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
    }
    //配置swagger的docket实列
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev");
        //通过environment.acceptsProfiles来判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("小张")
                .enable(flag)  //enable是否启动swagger，如果为false,则在浏览器中不能使用
                .select()
                //RequestHandlerSelectors 配置需要扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation 扫描方法下的注解
                 .apis(RequestHandlerSelectors.basePackage("com.zhang.controller"))
               //.apis(RequestHandlerSelectors.any())
                //.apis(RequestHandlerSelectors.none())
               //paths 过滤
                //ant 配置过滤的路径
                //PathSelectors还有any()、none()
               // .paths(PathSelectors.ant("com/zhang/**"))
                .build();
    }
    //配置swagger信息，apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("小张同学","https://blog.youkuaiyun.com/qq_45621392","dreamzxj@qq.com");
        return new ApiInfo(
                "小张同学的开发文档",
                "即使在小的帆也能远航",
                "v1.0",
                "https://blog.youkuaiyun.com/qq_45621392",
                contact,
                "Apache 2.0",
                "http: //www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

usercontrollet.java

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello";
    }
    @GetMapping("/map")
    public String map() {
        return "man";
    }

    @PostMapping("/user")
    public User user() {
        return new User();
    }
    //Operation接口，不是放在类上，是放在方法上
    @ApiOperation("Hello控制类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名")String username) {
        return "你好"+username;
    }
 //Operation接口，不是放在类上，是放在方法上
    @ApiOperation("Post测试")
    @PostMapping("/post")
    public User user(@ApiParam("用户名")String username,@ApiParam("密码")String password) {
        int i = 5/0;
        return new User();
    }
}

总结注解

Swagger注解说明

• @Api：用在类上，说明该类的作用
• @ApiOperation：给API增加方法说明。
• @ApiImplicitParams : 用在方法上包含多个参数说明。
• @ApiImplicitParam：用在方法上包含一个参数说明。
• paramType：指定参数放在哪个地方。
• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：说明参数
• defaultValue：参数的默认值

注：paramType类型

• header：请求参数放置于Request Header，使用@RequestHeader 获取。
• query：请求参数放置于请求地址，使用@RequestParam获取
• path：用于restful接口。
• @PathVariable：获取请求参数。 body form
• （5）@ApiResponses：用于表示一组响应。
• （6）@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。
• code：数字，例如400。
• message：信息，例如"请求参数没填好"。
• response：抛出异常的类 。
• （7）@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）。
• （8）@ApiModelProperty：描述一个model的属性。