swagger的用法

第一步：使用Swagger之前需要我们先新建一个SpringBoot项目，接口API是RESTful 风格

第二步：在pom.xml中引入swagger的依赖，当前版本为1.9.0

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

第三步：主启动类上添加 @EnableSwagger2Doc注解

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.spring4all.swagger.EnableSwagger2Doc;

@SpringBootApplication
@EnableSwagger2Doc
public class Swager2Application {
	public static void main(String[] args) {
		SpringApplication.run(Swager2Application.class, args);
	}
}

第四步：在yum文件或者application.properties文件中添加swagger的配置信息

各个配置参数说明：

swagger.enabled：表示是否开启swagger，true为开启，false为不开启

swagger.title：接口文档的标题

swagger.description：接口文档的描述

swagger.license：许可证，一般默认取值为Apache License,Version 2.0

swagger.licenseUrl：许可证URL，一般默认取值为https://www.apache.org/licenses/LICENSE-2.0.html

swagger.terms-of-service-url：服务条款URL，一般默认取值为https://github.com/dyc87112/spring-boot-starter-swagger

swagger.contact.name：接口维护人姓名

swagger.contact.url：接口维护人的Url，一般情况下这个地方为空就行

swagger.contact.email：接口维护人的邮箱

swagger.base-package：指定swagger扫描的基础包，默认：全扫描

swagger.base-path：需要处理的基础URL规则，默认：/**

swagger.exclude-path：指定在basePath基础上需要排除的url规则，配置文件中可不配置该字段，示例写法为：swagger.exclude-path=/error,/ops/**

swagger.version：指定当前接口文档的版本

 yum文件中的配置示例

#swagger配置
swagger:
  enabled: true
  title: 
  description: 
  license: Apache License,Version 2.0
  license-url: https://www.apache.org/licenses/LICENSE-2.0.html
  terms-of-service-url: https://github.com/dyc87112/spring-boot-starter-swagger
  contact:
    name: 
    url: 
    email: 
  base-package: com.*.controller
  base-path: /**
  version: 

 application.properties文件的配置示例

swagger.title=
swagger.description=
swagger.version=
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=
swagger.contact.url=
swagger.contact.email=
swagger.base-package=com.example.controller
swagger.base-path=/**

 第五步：启动项目，在浏览器中打开http://localhost:8080/swagger-ui.html，成功以后效果如图所示

  常用注解说明：

   @Api(tags = "xxx",description="description about xxx") :该注解作用于Controller类上面，tags的取值表示给该Controller类取一个标签名为"xxx"

   @ApiOperation(value="提交信息",notes="提交用户填写的信息至后台")：该注解作用于方法上，value的取值说明方法的用途，notes表示方法的备注说明

   @ApiModel(description=“x”)和@ApiModelProperty(“x”)：是用来给实体类添加说明，使用该注解时一定要注意该实体类一定是被作为请求体传递到Controller中，否则的话，即使添加了该注解在h5文档页面也不会有任何效果

@Data
@ApiModel(description="用户实体类")
public class User {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private Integer age;
}

   @ApiParam：该注解作用在请求参数处，value表示该请求参数的描述，required表示该请求参数是否必传

@RequestMapping(value = "/qryUser",method = RequestMethod.POST)
public CommonResult qryUser(@RequestBody @ApiParam(value = "用户请求实体",required = true) User user) {
    String id = request.getId();
    return userService.qryUser(id);
}

   @ApiImplicitParams与@ApiImplicitParam：@ApilmplicitParams注解用在请求的方法上，包含一组参数说明，@ApilmplicitParam用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息

  name：表示参数名

  value：该参数的汉字说明解释

  required：该参数是否必须传

  paramType：该参数放在那个地方，其取值有header、query、path、body（不常用）和form（不常用）

           值为“header”时，表示该请求参数是从@RequestHeader中获取；

           值为“query”时，表示该请求参数是从@RequestParam中获取；

           值为“path”时，表示该请求参数是从@PathVariable中获取

   dataType：参数类型，默认String，其它值dataType="Integer"

   defaultValue：参数的默认值

@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})

   

   

<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <swaggerInput>http://localhost/v2/api-docs</swaggerInput>
                    <!---->
                    <outputFile>D:\test\接口文档</outputFile>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <!--获取该目录下所有的adoc文件-->
                    <sourceDirectory>D:\test</sourceDirectory>
                    <!--将生成的文件保存到该文件下面-->
                    <outputDirectory>D:\test2</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
            </plugin>

参考地址：https://www.jianshu.com/p/f0b1ed00c411