IT序号网

springboot配置swagger-rest文档

shasha 2021年06月14日 编程语言 326 0

前言

swagger是一个很好的restful形式的api文档,可以通过比较小的侵入来提供很好的restful的文档。因为swagger是依赖服务生成的,所以其实是依赖服务的,这也算是它的一个小缺点吧。但是其实如果一个项目习惯去手写文档之后,也是可以的,但是新的项目还是建议去用一些自动生成的文档,省去了很多麻烦。

spring boot配置swagger

引入swagger依赖

<dependency> 
    <groupId>io.springfox</groupId> 
    <artifactId>springfox-swagger2</artifactId> 
    <version>2.2.2</version> 
</dependency> 
<dependency> 
    <groupId>io.springfox</groupId> 
    <artifactId>springfox-swagger-ui</artifactId> 
    <version>2.2.2</version> 
</dependency> 

    
     

编写swagger对应的配置

import org.springframework.context.annotation.Bean; 
import org.springframework.context.annotation.Configuration; 
import springfox.documentation.builders.ApiInfoBuilder; 
import springfox.documentation.builders.PathSelectors; 
import springfox.documentation.builders.RequestHandlerSelectors; 
import springfox.documentation.service.ApiInfo; 
import springfox.documentation.spi.DocumentationType; 
import springfox.documentation.spring.web.plugins.Docket; 
import springfox.documentation.swagger2.annotations.EnableSwagger2; 

@Configuration
@EnableSwagger2
public class SwaggerConfig {

@<span class="hljs-type">Bean</span> 
<span class="hljs-keyword">public</span> <span class="hljs-type">Docket</span> createRestApi() { 
                <span class="hljs-comment">// 文档类型</span> 
    <span class="hljs-keyword">return</span> new <span class="hljs-type">Docket</span>(<span class="hljs-type">DocumentationType</span>.<span class="hljs-type">SWAGGER_2</span>) 
            <span class="hljs-comment">// 创建api的基本信息</span> 
            .apiInfo(apiInfo()) 
            <span class="hljs-comment">// 选择哪些接口去暴露</span> 
            .select() 
            <span class="hljs-comment">// 扫描的包</span> 
            .apis(<span class="hljs-type">RequestHandlerSelectors</span>.basePackage(<span class="hljs-string">"com.demo.web.controller"</span>)) 
            .paths(<span class="hljs-type">PathSelectors</span>.any()) 
            .build(); 
} 
 
<span class="hljs-keyword">private</span> <span class="hljs-type">ApiInfo</span> apiInfo() { 
    <span class="hljs-keyword">return</span> new <span class="hljs-type">ApiInfoBuilder</span>() 
            .title(<span class="hljs-string">"groundhog-web swagger文档"</span>) 
            .contact(<span class="hljs-string">"name"</span>) 
            .version(<span class="hljs-string">"1.0"</span>) 
            .build(); 
} 

}

在api和请求参数中使用注解

接口中使用swagger注解

@RestController 
@Api(value = "测试swagger", description = "测试swagger api") 
public class TestSwaggerController { 
<span class="hljs-variable">@ApiOperation</span>(value = <span class="hljs-string">"返回url中的参数"</span>, notes = <span class="hljs-string">"返回url中的参数"</span>) 
<span class="hljs-variable">@ApiImplicitParam</span>(name = <span class="hljs-string">"id"</span>, value = <span class="hljs-string">"id值"</span>, paramType = <span class="hljs-string">"path"</span>, required = true, dataType = <span class="hljs-string">"Integer"</span>) 
<span class="hljs-variable">@GetMapping</span>(path = <span class="hljs-string">"/getUrlParam/{id}"</span>) 
public Integer getUrlParam(<span class="hljs-variable">@PathVariable</span>(value = <span class="hljs-string">"id"</span>) Integer id) { 
    <span class="hljs-selector-tag">return</span> <span class="hljs-selector-tag">id</span>; 
} 

}

可以访问localhost:port/swagger-ui.html看到生成的swagger文档。可以看到请求结果:

在这里插入图片描述

也可以看到之前post方法的接口也可以生成对于的参数文档,这里也可以对表单参数bean使用@ApiModel和@ApiProperty注解进行标识。

在这里插入图片描述

swagger相关注解和官方文档

swagger常用注解:

  1. @Api:修饰整个类,描述controller的作用
  2. @ApiOperation:描述一个类的一个方法,或者说一个接口
  3. @ApiParam:单个参数描述
  4. @ApiModel:用对象来接收参数
  5. @ApiProperty:用对象接收参数时,描述对象的一个字段
  6. @ApiImplicitParam:一个请求参数
  7. @ApiImplicitParams:多个请求参数

这里推荐下官方文档,感兴趣可以看一下其他注解和相关配置:

[注解官方文档](

               原文地址:https://blog.csdn.net/zlj1217/article/details/82829891                 </div> 

评论关闭
IT序号网

微信公众号号:IT虾米 (左侧二维码扫一扫)欢迎添加!