1.入门：

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

1. 先引入maven依赖：
   swagger有两个部分，一个是swagger本体，一个是ui。

	<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>
1
2
3
4
5
6
7
8
9
10
11

启动时遇到一个 空指针 的bug，查了一下可能是因为我的 springboot 和 swagger 版本不匹配，百度了之后只能降springboot的版本或者升级swagger的版本。

2. 添加一个swagger的config类：
   我自己重写了一个 ApiInfo类进行自定义信息的编写，但是查看源码我们发现这个类的参数是没有set方法的，也就是说我们只有通过构造方法来给一个 ApiInfo 对象进行赋值。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置作者信息
    public static final Contact contact = new Contact("wyh", "xxx", "wyh8421@163.com");
    
    @Bean
    public Docket getDocket(){
        //先选择版本，一共有三个版本，选择swagger2版本
        //后面的 apiInfo 是自定义的 api 的详细信息：Docket apiInfo(ApiInfo apiInfo)
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    //我们自定义我们的api信息
    public ApiInfo apiInfo(){
        //public ApiInfo(String title, String description, String version,
        // String termsOfServiceUrl, Contact contact, String license, String licenseUrl,
        // Collection<VendorExtension> vendorExtensions)
        return new ApiInfo("wyh的测试", "现在开始测试！","v 1.0","https://blog.csdn.net/weixin_45886859?spm=1000.2115.3001.5343",contact,
                "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

效果：http://localhost:1126/swagger-ui.html

3. 报错：
   在入门过程中我遇到了两种报错，一种是报空指针，一种是报找不到我的 swagger-ui 的页面。
   使用以下就能解决。

Springboot2.6.x以上的避免空指针异常，在启动类加注解@EnableWebMvc
访问接口文档页面404的，可以配置一个实现WebMvcConfigurer的类
@Configuration
public class WebMVCConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler(“/").addResourceLocations(“classpath:/static/”);
/
* 配置swagger-ui显示文档
*/
registry.addResourceHandler(“swagger-ui.html”)
.addResourceLocations(“classpath:/META-INF/resources/”);
registry.addResourceHandler(”/webjars/**")
.addResourceLocations(“classpath:/META-INF/resources/webjars/”);
}

}

2.资源的扫描：

@Bean
    public Docket getDocket(){
        //先选择版本，一共有三个版本，选择swagger2版本
        //后面的 apiInfo 是自定义的 api 的详细信息：Docket apiInfo(ApiInfo apiInfo)
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                //根据方法上的注解进行扫描：在页面上只显示被 GetMapping 注解修饰的方法
//                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                //根据类上的注解进行扫描：在页面上只显示被 RequestMapping 注解修饰的类
                .apis(RequestHandlerSelectors.withClassAnnotation(RequestMapping.class))
                //扫描所有
//                .apis(RequestHandlerSelectors.any())
                //根据包进行扫描
//                .apis(RequestHandlerSelectors.basePackage("com.swaggerdemo.controller"))
                //拦截指定的资源
//                .paths(PathSelectors.ant("/SwaggerConfig/**"))
                .build();
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1. 分组：
   不同的成员拥有不同的Docket，不同的Docket设置了不同的groupName。

@Bean
    public Docket DocketInit1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("a");
    }
    @Bean
    public Docket DocketInit2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("b");
    }
    @Bean
    public Docket getDocket(){
        //先选择版本，一共有三个版本，选择swagger2版本
        //后面的 apiInfo 是自定义的 api 的详细信息：Docket apiInfo(ApiInfo apiInfo)
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("wyh")
                .select()
                .build();
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

通过不同的组名显示不同的页面作者信息

2. models
   使用@ApiOperation() 注解为方法设置提示
   使用@ApiParam() 注解为参数设置提示

@RestController
@RequestMapping("/")
public class MyController {
    @ApiOperation(value = "hello呀")
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String myMethod(){
        return "hello";
    }
    @ApiOperation(value = "hello的测试呀")
    @GetMapping("/test")
    public String testMethod(){
        return "test2";
    }
    @ApiOperation(value = "hello的测试呀")
    @PostMapping("/user")
    public user userLogin(@ApiParam("姓名") String name,String password){
        user user = new user(name,password);
        return user;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

3. 进行在线测试：
   models中就是我们实体类的信息
   
   通过点击页面上的 Try it Out 键，进行在线的测试：
   
   点击 Execute 进行测试，测试结果会显示在下面。