Swagger_Java

使用Swagger 1. 导入maven依赖


    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    2.9.2

2. 编写hello程序

package com.cai.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String hello() {
        return "hello";
    }
}

3. 添加配置类

package com.cai.config;

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

@Configuration	// 相当于bean.xml
@EnableSwagger2 // 开启Swagger 
public class SwaggerConfig {

}

4. 测试运行：http://localhost:8080/swagger-ui.html

5. 配置Swagger 参考源码来做

package com.cai.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
@EnableSwagger2
public class SwaggerConfig {

    // 配置需要实例Docket参考源码
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo());
    }

    // 配置Swagger信息=apiInfo
    private ApiInfo apiInfo() {
        // 从源码拿的
        Contact contact = new Contact("蔡文杰", "https://blog.csdn.net/caiwenjie_____?type=blog", "1257791157@qq.com");
        return new ApiInfo(
                "SwaggerAPI文档",
                "跟着狂神学习Java",
                "1.0",
                "https://blog.csdn.net/caiwenjie_____?type=blog",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

6. 配置Swagger扫描接口

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // RequestHandlerSelectors 配置扫描接口方式
                // .basePackage 扫描包
                // withClassAnnotation 指定注解的类就会被扫描
                // withMethodAnnotation 指定注解的方法就会被扫描
                .apis(RequestHandlerSelectors.basePackage("com.cai"))
                // 过滤请求 ant指定请求方式仅扫描
                .paths(PathSelectors.ant("/hello"))
                .build();
    }

7. 配置是否启动Swagger

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false) // 关闭swagger
            // RequestHandlerSelectors 配置扫描接口方式
            // .basePackage 扫描包
            // withClassAnnotation 指定注解的类就会被扫描
            // withMethodAnnotation 指定注解的方法就会被扫描
            // 过滤请求 ant指定请求方式仅扫描
            .select().apis(RequestHandlerSelectors.basePackage("com.cai")).paths(PathSelectors.ant("/hello"))
            .build();
}

8. 生产环境不开启Swagger

application.properties
- spring.profiles.active=dev
application-dev.properties
- server.port=8081
application-pro.properties
- server.port=8082

@Bean
public Docket docket(Environment environment) {
    // 指定环境开启Swagger
    Profiles profiles = Profiles.of("dev","test");
    // 判断环境是否存在
    boolean flag = environment.acceptsProfiles(profiles);
    System.out.println(flag);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag) // 关闭swagger
            // RequestHandlerSelectors 配置扫描接口方式
            // .basePackage 扫描包
            // withClassAnnotation 指定注解的类就会被扫描
            // withMethodAnnotation 指定注解的方法就会被扫描
            // 过滤请求 ant指定请求方式仅扫描
            .select().apis(RequestHandlerSelectors.basePackage("com.cai")).paths(PathSelectors.ant("/hello"))
            .build();
}

9. 配置Swagger文档API文档分组

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("开发团队-02");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("开发团队-03");
}

// 配置需要实例Docket参考源码
@Bean
public Docket docket(Environment environment) {
    // 指定环境开启Swagger
    Profiles profiles = Profiles.of("dev", "test");
    // 判断环境是否存在
    boolean flag = environment.acceptsProfiles(profiles);
    System.out.println(flag);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("开发团队-01")
            .enable(flag) // 关闭swagger
            // RequestHandlerSelectors 配置扫描接口方式
            // .basePackage 扫描包
            // withClassAnnotation 指定注解的类就会被扫描
            // withMethodAnnotation 指定注解的方法就会被扫描
            // 过滤请求 ant指定请求方式仅扫描
            .select().apis(RequestHandlerSelectors.basePackage("com.cai")).paths(PathSelectors.ant("/hello"))
            .build();
}

10.备注请求备注实体

package com.cai.controller;

import com.cai.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@RestController
public class HelloController {

    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String hello() {
        return "hello";
    }

    // 返回实体类会被扫描
    @PostMapping(value = "/user")
    public User user() {
        return new User();
    }

    // 给方法备注
    @ApiOperation("hello控制类")
    @GetMapping(value = "/hello2")
    // 参数备注
    public String hello2(@ApiParam("用户名") String username) {
        return "hello" + username;
    }
}

package com.cai.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public String getPassword() {
        return password;
    }
}

总结

接口可以备注
接口文档实时更新
可以在线测试

Swagger

Java相关栏目本月热门文章