SpringBoot_接口文档_Swagger2

约定不等于承诺〃 2021-10-06 03:34 521阅读 0赞

### SpringBoot\_接口文档\_Swagger2 ###

*  依赖pom.xml
 *  配置文件bootstrap.yml
 *  配置源码
 *  Swagger2常用注解
 *  Swagger2Adoc生成文档

# 依赖pom.xml #

<dependency>
    		<groupId>io.springfox</groupId>
    		<artifactId>springfox-swagger2</artifactId>
    	</dependency>
    	<dependency>
    		<groupId>io.springfox</groupId>
    		<artifactId>springfox-swagger-ui</artifactId>
    	</dependency>
    	
    	<dependency>
    		<groupId>io.github.swagger2markup</groupId>
    		<artifactId>swagger2markup</artifactId>
    		<version>1.3.1</version>
    	</dependency>

# 配置文件bootstrap.yml #

#-----------swagger2配置---------------
    pingruan.base.api-package-scan=com.plxc.service.controller
    pingruan.base.api-title=demo
    pingruan.base.api-desc=api demo doc

# 配置源码 #

/**
         * swagger2 api配置
         *
         * @author vander
         * @date 2018年11月15日
         */
        @Configuration
        @EnableSwagger2
        @Slf4j
        public class Swagger2Config {
        	
        	@Autowired
        	private BProperties bProperties;
        	
            @Bean
            public Docket createRestApi() {
            	log.info("swagger2 scanning package :"+bProperties.getApiPackageScan());
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage(bProperties.getApiPackageScan()))
                        .paths(PathSelectors.any())
                        .build();
            }
        
            private ApiInfo apiInfo() {
                return new ApiInfoBuilder()
                        .title(bProperties.getApiTitle())
                        .description(bProperties.getApiDesc())
                        .version("1.0")
                        .build();
            }
        
        }
    
    @SpringBootApplication
    @EnableSwagger2
    public class SpringbootSwagger2Application {
    
    	public static void main(String[] args) {
    		SpringApplication.run(SpringbootSwagger2Application.class, args);
    	}
    }

# Swagger2常用注解 #

@Api：用在请求的类上，表示对类的说明
        tags="说明该类的作用，可以在UI界面上看到的注解"
        value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
     
    @ApiOperation：用在请求的方法上，说明方法的用途、作用
        value="说明方法的用途、作用"
        notes="方法的备注说明"
     
    @ApiImplicitParams：用在请求的方法上，表示一组参数说明
        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
            name：参数名
            value：参数的汉字说明、解释
            required：参数是否必须传
            paramType：参数放在哪个地方
                · header --> 请求参数的获取：@RequestHeader
                · query --> 请求参数的获取：@RequestParam
                · path（用于restful接口）--> 请求参数的获取：@PathVariable
                · body（不常用）
                · form（不常用）    
            dataType：参数类型，默认String，其它值dataType="Integer"       
            defaultValue：参数的默认值
     
    @ApiResponses：用在请求的方法上，表示一组响应
        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
            code：数字，例如400
            message：信息，例如"请求参数没填好"
            response：抛出异常的类
     
    @ApiModel：用于响应类上，表示一个返回响应数据的信息
                （这种一般用在post创建的时候，使用@RequestBody这样的场景，
                请求参数无法使用@ApiImplicitParam注解进行描述的时候）
        @ApiModelProperty：用在属性上，描述响应类的属性

# Swagger2Adoc生成文档 #

<plugin>
    	<groupId>org.asciidoctor</groupId>
    	<artifactId>asciidoctor-maven-plugin</artifactId>
    	<version>1.5.6</version>
    	<configuration>
    		<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
    		<outputDirectory>src/docs/asciidoc/html</outputDirectory>
    		<backend>html</backend>
    		<sourceHighlighter>coderay</sourceHighlighter>
    		<attributes>
    			<toc>left</toc>
    		</attributes>
    	</configuration>
    </plugin>
    
    /**
     * 1、生成swagger静态文件(src/docs/asciidoc/generated/all)
     * 2、copy vander-framework-common的pom.xml中的asciidoctor:process插件
     * 3、mvn asciidoctor:process-asciidoc(src/docs/asciidoc/html)
     * @return
     */
    @Bean
    public Swagger2Adoc swagger2Adoc() {
    	return new Swagger2Adoc(bProperties.getProjectIdPort());//指定项目ip和port，如http://localhost:8083
    }
    
    
    public static class Swagger2Adoc {
    	private String rootPath;
    	public Swagger2Adoc(String rootPath) {
    		this.rootPath = rootPath;
    	}
    	public void gen() throws MalformedURLException {
    		// 输出Ascii格式
    		Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
    				.build();
    		Swagger2MarkupConverter.from(new URL(rootPath+"/v2/api-docs")).withConfig(config).build()
    				.toFile(Paths.get("src/docs/asciidoc/generated/all"));
    	}
    }